Generate images from text prompts
🤖/image/generate generates images from text prompts using AI.

Usage example
Upload a 1024×1024 source in the image field and a matching white-on-black edit mask in the mask field. This example preserves every decoded source pixel outside the mask:
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"inpainted": {
"format": "png",
"inpainting": "strict",
"model": "google/nano-banana-pro",
"prompt": "Replace the masked area with a breaching whale. Keep the rest of the image unchanged.",
"robot": "/image/generate",
"use": [
{
"as": "image",
"fields": "image",
"name": ":original"
},
{
"as": "mask",
"fields": "mask",
"name": ":original"
}
]
}
}
}Parameters
interpolateboolean | Record<string, boolean>Controls whether Assembly Variables are interpolated for individual instruction fields.
By default, most Robot instruction fields interpolate Assembly Variables. Set this to
falseto treat every instruction field as literal text, or set an individual field path tofalseto treat only that field as literal text. For Robot-specific fields that are literal by default, set this totrueor set that field path totrueto opt back into interpolation.Use field names such as
path, or dotted paths such asffmpeg.vffor nested objects.output_metaRecord<string, boolean> | boolean | Array<string>Requests CPU-intensive metadata, disabled by default for faster Assemblies.
For images,
"has_transparency": truedetects transparency and"dominant_colors": trueextracts hex colors. Add"dominant_colors_sampled": truefor faster, approximate colors from downscaled frames. Sampling requiresdominant_colorsand changes neither image bytes nor billing. Its method and palette may vary. Omit or disable it for full-resolution colors.For images, you can also add
"blurhash": trueto extract a BlurHash string — a compact representation of a placeholder for the image, useful for showing a blurred preview while the full image loads.For images,
"thumbhash": trueinstead extracts a base64-encoded ThumbHash intometa.thumbhash, together withmeta.has_alpha(whether an alpha channel exists, even when fully opaque). It describes EXIF-oriented pixels and uses the first frame of animated images. Extraction is best-effort: images above 40 megapixels, unsupported formats, or a failed/bounded decode produce no placeholder. Successful extraction adds a metadata charge equivalent to 20% of that file's bytes. No ThumbHash surcharge applies when disabled or when no hash is produced.Set this option on the Step producing the image, such as
/upload/handlefor uploaded originals or/image/resizefor processed outputs. Setting it only on/transloadit/storedoes not request extraction: storage preserves the producer's metadata. Transloadit Storage persists a generated hash with its immutable version and returns it in stored results and native asset reads. Direct S3 uploads do not generate placeholders. A placeholder contains image information, so protect it with the same access controls as the full image.For videos, you can add the
"colorspace": trueparameter to extract the colorspace of the output video.For videos, you can also add
"interlaced": trueto detect whether the video is interlaced. This combines the cheap ffprobefield_orderflag with a boundedidetsampling pass over the first frames of the source, exposinginterlaced,field_order, and a diagnosticinterlace_detectionobject underfile.meta. This is computationally expensive and billed accordingly.For audio, you can add
"mean_volume": trueto get a single value representing the mean average volume of the audio file.You can also set this to
falseto skip metadata extraction and speed up transcoding.user_metaRecord<string, any>(default:{})Adds custom JSON metadata to each emitted file without changing its contents. Nested objects and arrays are supported.
Inheritance depends on the Robot. Values merge with existing
user_metaon the output file; the current Step replaces matching top-level keys. Assign required keys explicitly when a Robot creates fresh outputs.In processing Steps,
${file.*}refers to the first input and${result.*}to the emitted file. Values are evaluated per output after the Robot runs, before subsequent metadata extraction and temporary storage. On:original, values are evaluated per upload before metadata extraction.Downstream Steps read
${file.user_meta.key}. See Custom metadata for a complete example and inheritance rules.resultboolean(default:false)Whether the results of this Step should be present in the Assembly Status JSON
queuebatchSetting the queue to 'batch', manually downgrades the priority of jobs for this step to avoid consuming Priority job slots for jobs that don't need zero queue waiting times
force_acceptboolean(default:false)Force a Robot to accept a file type it would have ignored.
By default, Robots ignore files they are not familiar with. 🤖/video/encode, for example, will happily ignore input images.
With the
force_acceptparameter set totrue, you can force Robots to accept all files thrown at them. This will typically lead to errors and should only be used for debugging or combatting edge cases.ignore_errorsboolean | Array<meta | execute>(default:[])Ignore errors during specific phases of processing.
Setting this to
["meta"]will cause the Robot to ignore errors during metadata extraction.Setting this to
["execute"]will cause the Robot to ignore errors during the main execution phase.Setting this to
trueis equivalent to["meta", "execute"]and will ignore errors in both phases.usestring | Array<string> | Array<object> | objectSpecifies which Step(s) to use as input.
For inpainting, select source and mask with upload fields or
use.asroles.Multiple source selectors fail with “Supply exactly one inpainting source image.” Competing edit selectors, including both edit roles on one input, fail with “Supply exactly one inpainting mask or cutout.” An edit field overrides inherited edit roles.
Accepted input forms:
- Select image and mask/cutout fields. Fields override inherited roles.
- Without fields, use image and mask/cutout roles. Repeated use entries combine roles.
- Mix an image field and edit role, or an image role and edit field.
- With an edit selector but no image selector, the first non-mask input is the source.
- A transparent cutout with image intent is its own source, including beside references.
- Legacy image+mask pairs use first tagged source, second tagged mask; references do not affect selection. Fields win.
- Replicate accepts 3+ image+mask uploads, uses the first two unless fields select them, and ignores references.
- Replicate alone accepts untagged source-first, mask-second inputs, honoring a unique image selector.
- Strict accepts a sole transparent image, including a mask-only upload, as source and cutout; best_effort refuses the mask-only form.
- Other inputs stay references. Untagged transparency never enables Google/OpenAI best_effort editing. Mark masks/cutouts with a field or use.as role.
Mask formats (source and mask must have matching dimensions):
- Opaque black-and-white masks edit white and protect black (average RGB threshold: 128). Use black and white to avoid ambiguous opaque colors.
- A mask with transparency edits pixels with alpha below 128 and protects the rest.
- Legacy green masks edit pixels with alpha at least 128 when every such pixel is green (green at least 128 and greater than red and blue). Transparent pixels are protected.
- A cutout edits alpha below 128. A separate source supplies protected pixels; otherwise only the cutout’s remaining pixels can be preserved. Alongside references, give the cutout an image field or role to select it as the source.
Source and mask must be rasters with matching display dimensions, at most 40,000,000 pixels each (16,777,216 in strict). Strict refuses SVG/SVGZ; best_effort decoding draws them once. Best-effort applies EXIF orientation and uses the first frame; strict requires one frame and applied orientation.
Masks are converted for each provider. Supported inpainting models:
google/nano-banana,google/nano-banana-2,google/nano-banana-pro,openai/gpt-image-2,openai/gpt-image-2.5-flare,openai/gpt-image-2.5-sunburst,openai/gpt-image-2.6-flare,openai/gpt-image-2.6-sunburst,stability-ai/stable-diffusion-inpainting. The legacygpt-image-2alias uses the same OpenAI route. FLUX, Recraft and legacy self-hosted Stable Diffusion do not have an inpainting route here; inpainting requests are refused instead of silently ignoring a mask. Ordinary non-masked generation retains its existing behavior.Without strict mode the full provider image is returned; masks only guide it. Exterior content, colors, size or transparency can change, even with a fixed seed. Select strict for exact exterior pixels. Auxiliary images such as gain maps are not retained in strict PNG output.
Strict mode uses the source canvas without resizing. Google requires a native canvas: at 1K, Nano Banana accepts 1024×1024, 864×1184, 1184×864, 768×1344 or 1344×768; Nano Banana Pro and Nano Banana 2 accept 1024×1024, 896×1200, 1200×896, 768×1376 or 1376×768, with 2× and 4× sizes also accepted within the pixel limit. OpenAI canvas edges must be multiples of 16, no longer than 3840 pixels, with an aspect ratio no greater than 3:1 and 655,360–8,294,400 pixels in total. Replicate inpainting requires each edge to be a multiple of 64, from 64 to 1024 pixels. Unsupported canvases fail before generation; an unexpectedly different provider result also fails. Resize the source and mask together in an earlier Step if needed.
modelstringThe AI model to use. Defaults to
openai/gpt-image-2.5-flare. Supported models includeflux-1.1-pro-ultra,flux-schnell,recraft-v3,google/nano-banana,google/nano-banana-2,google/nano-banana-pro,openai/gpt-image-2,openai/gpt-image-2.5-flare,openai/gpt-image-2.5-sunburst,openai/gpt-image-2.6-flare,openai/gpt-image-2.6-sunburst, andstability-ai/stable-diffusion-inpainting. The legacy aliasgpt-image-2is also accepted for backwards compatibility.prompt— requiredstringPrompt describing the desired image. For inpainting, describe what should appear in the masked/transparent region and that the rest should stay unchanged.
formatjpeg | jpg | png | webp | svgOutput format. Defaults depend on model: png for Google and OpenAI models, svg for recraft-v3, jpeg for others. Google may return JPEG bytes in best_effort mode even when png is requested; strict mode encodes PNG locally.
inpaintingbest_effort | strict(default:"best_effort")best_effort normalizes masks and returns the full provider result. strict copies decoded source RGBA outside the hard-thresholded mask and provider RGBA inside, preserving alpha; no feathering or extra AI call. Strict needs matching raster canvases, format png, single-frame 8-bit sRGB source/output without embedded profiles, and applied orientation. Masks may be 8-bit grayscale without profiles. Each image is limited to 16,777,216 pixels. Watermarked plans are refused. Width/height must match the source; omitted dimensions use its size. Omit aspect_ratio. Model-native canvas limits apply. Incompatible inputs or results fail. PNG metadata/file bytes can change; downstream resizing, watermarking or lossy encoding can change pixels.
seedstring | numberSeed for the random number generator. For Google models, use an integer from 0 to 2147483647. Each output increments the seed by 1, so the final output’s seed must also fit this range. A seed does not guarantee identical images.
aspect_ratiostringRequested output aspect ratio. For Google models, width/height can also be used and orientation is derived automatically when aspect_ratio is omitted.
heightstring | numberRequested output height in pixels (mainly used by Google and OpenAI image models).
widthstring | numberRequested output width in pixels (mainly used by Google and OpenAI image models).
stylestringStyle of the generated image.
num_outputsstring | numberNumber of output variants to generate (1-10).