Create a generation

$ luma-agents-cli generations create

POST/generations

Submit an image or video generation job. Returns immediately with an opaque job ID to poll via GET /generations/{id}.

ParametersExpand Collapse

--prompt: string

Text prompt

--aspect-ratio: optional "3:1" or "2:1" or "21:9" or 9 more

Output aspect ratio. Valid values depend on the selected model and generation type; the server validates the final model-specific set.

--image-ref: optional array of ImageRef { data, file_id, generation_id, 2 more }

Reference images for style/content guidance. Up to 9 for type 'image', up to 8 for type 'image_edit'.

--layering: optional object { resolution }

Layer-extraction options for type=layering (model uni-1). The image to decompose rides body.source; body.prompt optionally guides how to split it (max 500 characters). The server plans the layers automatically before generating.

--model: optional "uni-1" or "uni-1-max" or "ray-3.2"

Model identifier. uni-1 is the default image tier; uni-1-max produces higher-quality output than uni-1 at a higher per-image price. ray-3.2 is the public video model for text-to-video, image-to-video, and video-to-video editing.

--output-format: optional "png" or "jpeg"

Output image format

--source: optional object { data, file_id, generation_id, 2 more }

Media reference for guided generation. Provide exactly one of url, inline base64 data, generation_id, or file_id. URL/data references accept image media at image positions; video_edit and video_reframe sources also accept source.url or source.data when source.media_type is a video/* MIME. generation_id chains image_edit off a prior image output, video_edit/video_reframe off a prior video output, and video.start_frame/end_frame for extension. file_id references a file previously uploaded via POST /files — see the Files API.

--style: optional "auto" or "manga"

Style preset (auto, manga)

--type: optional "image" or "image_edit" or "video" or 3 more

The kind of generation to perform

--user-id: optional string

Your end-user's stable opaque identifier (no PII). Forwarded to upstream model providers as their per-user tagging field so trust & safety violations can be attributed to a specific end-user rather than the whole API account. Also used for per-end-user usage breakdowns in /v1/usage. Strongly recommended for partner integrations.

--video: optional object { duration, edit, end_frame, 9 more }

Ray 3.2 video request options. Common output settings live at the top level for type=video, type=video_edit, and type=video_reframe; video-to-video conditioning lives under edit.

--web-search: optional boolean

Enable web search grounding — the agent can search the web and download reference images before generating.

ReturnsExpand Collapse

generation: object { id, created_at, model, 5 more }

Generation status and output

id: string

Generation identifier

created_at: string

Creation timestamp

model: "uni-1" or "uni-1-max" or "ray-3.2"

Model used

"uni-1"

"uni-1-max"

"ray-3.2"

state: "queued" or "processing" or "completed" or "failed"

Current state of the generation

"queued"

"processing"

"completed"

"failed"

type: "image" or "image_edit" or "video" or 3 more

The kind of generation to perform

"image"

"image_edit"

"video"

"video_edit"

"video_reframe"

"layering"

failure_code: optional "content_moderated" or "generation_failed" or "budget_exhausted" or 6 more

Machine-readable failure code for programmatic handling

"content_moderated"

"generation_failed"

"budget_exhausted"

"output_not_found"

"image_too_large"

"unsupported_format"

"corrupt_input"

"invalid_request"

"rate_limited"

failure_reason: optional string

Human-readable failure description

output: optional array of GenerationOutput { type, url, layer }

Generated outputs (populated on completion)

type: string

Media type (e.g. image, video)

url: string

Presigned URL (1hr expiry)

layer: optional object { alpha_hint, description, index, 2 more }

Per-layer semantics for a type=layering output

alpha_hint: string

Edge treatment of the layer's transparency — soft (hair/fur/glass), hard (solid edges), or none (the opaque background)

description: string

Complete-element caption for the layer's content

index: number

Layer position, front-to-back; the last layer is the background

label: string

Short (1-2 word) layer name

bounds: optional object { canvas_height, canvas_width, height, 3 more }

Where a layer's returned pixels sit inside the full composite frame. Layer images are cropped to their visible-alpha bounding box, so layers of one stack have differing pixel dimensions. Composite onto a transparent canvas_width x canvas_height image by pasting each layer at (x, y), iterating the output list in reverse (back-to-front), to reconstruct the source frame.

canvas_height: number

Height of the full composite canvas the layers reassemble into

canvas_width: number

Width of the full composite canvas the layers reassemble into

height: number

Pixel height of the returned layer image

width: number

Pixel width of the returned layer image

x: number

Left offset of this layer's pixels within the composite canvas

y: number

Top offset of this layer's pixels within the composite canvas