Skip to main content
Get started
Node ReferenceImage Node
Node Reference

Image Node

Upload, crop, export, and reuse image files on the canvas.

Image nodes are static media nodes for uploaded files and image outputs that already exist on the canvas. They render the current local preview, synced media reference, or saved source URL, then keep the file metadata and non-destructive display transform with the node.

Image display is separate from image generation
Use the Image node to store, crop, export, and reuse an image. Use Image Generation when the workflow needs to create a new image from a prompt.

What it stores

  • The local preview fields, including src and blobKey, while the upload is available in the browser.
  • The durable R2-backed mediaRef after the file syncs.
  • File metadata such as fileName, mimeType, naturalWidth, naturalHeight, and aspectRatio.
  • Optional imageTransform data for contain, cover, or crop display behavior.

Add or replace an image

  1. Choose the Image node

    Add an Image node from the canvas toolbar, or drag compatible image files into the canvas. Toolbar placement decodes the image before placement so the initial size can match the source aspect ratio.

  2. Drop or select a file

    The node accepts file picker selection and drag-and-drop. A hidden input limits picker choices to supported image MIME types, while the shared media validator rejects unsupported or oversized files before commit.

  3. Let the preview and sync finish

    Builder Studio stages a local preview first, then syncs the file to durable media storage. The node switches to the R2 display URL when the media reference is available.

  4. Adjust the image

    Resize the node, crop it from the selected-node toolbar, export the transformed result, or run background removal when the source is a raster image.

Supported files

FormatMIME typeNotes
JPGimage/jpegSupported for upload, display, export, and background removal.
PNGimage/pngSupported for upload, display, export, and background removal.
GIFimage/gifSupported for upload and display.
WebPimage/webpSupported for upload, display, export, and background removal.
AVIFimage/avifSupported for upload, display, and export when the runtime can decode it.
SVGimage/svg+xmlSupported for upload and display. Background removal is not available.
Upload limit
Image uploads are capped at 50MB. Empty files, unknown media types, and files outside the accepted image list are rejected before the node writes media data.

Sizing and placement

Image nodes read native image dimensions before committing upload data. Builder Studio stores the natural width, natural height, and aspect ratio, then sizes the node to the true source pixels unless the image is larger than the canvas maximum. Large images are scaled down; small images are not upscaled.

  • Drag placement keeps the native aspect ratio while the pointer defines the target frame.
  • Existing image nodes preserve aspect-ratio resizing when the node has a valid stored aspectRatio.
  • Legacy images without dimensions update their missing dimensions after the active image element loads.

Crop and transform

Cropping is non-destructive. The original media remains intact, while the node stores an imageTransform that controls how the source is displayed and exported.

  • Select one Image node and use the crop button in the floating toolbar, or double-click the image surface, to enter crop editing.
  • Drag the crop rectangle, edges, or corners. Hold Shift on a corner drag to preserve the crop rectangle aspect ratio.
  • Press Enter or double-click the overlay to apply the crop. Press Escape to cancel.
  • A full-frame crop clears imageTransform; Reset crop also returns the node to the uncropped source.
  • Applying a crop reframes the node height from the crop aspect ratio so the selected image keeps its visible proportions.
imageTransform crop patchjson
{  "imageTransform": {    "mode": "crop",    "crop": {      "x": 0.12,      "y": 0.08,      "width": 0.76,      "height": 0.7    }  }}
Transform modes
The image transform contract supports contain, cover with an optional normalized focal point, and crop with normalized source x, y, width, and height. Use null or contain to clear a transform.

Selected image actions

ActionWhat it doesAvailability
Remove backgroundSends the current image, including an active transform, through the background removal pipeline and creates a new PNG Image node next to the source.Editable raster images with a synced media reference.
Reset cropClears the active crop transform.Editable image nodes that already have a crop.
Crop imageOpens or applies the crop editor.Editable image nodes with a visible image.
Export imageDownloads a PNG. Synced media exports through the server route; local-only previews fall back to a browser canvas export.Image nodes with a loaded source.
Expand imageOpens the selected image in the canvas lightbox.Image nodes with a visible source.

Background removal

Background removal works from the durable R2 media reference. If you click it before upload sync has finished, Builder Studio queues the intent and runs it when the synced reference arrives. The queue times out after 30 seconds if the media reference never becomes available.

  • SVG files can be uploaded and displayed, but they are rejected by the background removal API because the operation requires raster input.
  • Cropped or covered images pass the current transform, width, and height to the removal route so the output matches the visible image.
  • The result is saved as a PNG, receives fresh natural dimensions, and is inserted as a separate Image node offset from the original.

Agent and API notes

Agents should treat Image nodes as media references, not generation requests. To update a visible crop through the node patch contract, writeimageTransform with normalized values between 0 and 1. Keep the original mediaRef unless the agent is intentionally replacing the underlying image asset.

Was this page helpful?