# Generations ## Create a generation **post** `/generations` Submit an image or video generation job. Returns immediately with an opaque job ID to poll via GET /generations/{id}. ### Body Parameters - `prompt: string` Text prompt - `aspect_ratio: optional "3:1" or "2:1" or "21:9" or 10 more` Output aspect ratio. Valid values depend on the selected model and generation type; the server validates the final model-specific set. - `"3:1"` - `"2:1"` - `"21:9"` - `"16:9"` - `"4:3"` - `"3:2"` - `"1:1"` - `"4:5"` - `"3:4"` - `"2:3"` - `"9:16"` - `"1:2"` - `"1:3"` - `image_ref: optional array of ImageRef` Reference images for style/content guidance. Up to 9 for type 'image', up to 8 for type 'image_edit'. - `data: optional string` Base64-encoded image or video data - `file_id: optional string` UUID of a file previously uploaded via POST /files. Skips URL fetch / base64 decode and reuses the file's pre-moderated backing artifact. The referenced file must be owned by the same client and in state=ready. See the Files API for the upload flow. - `generation_id: optional string` UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension. - `media_type: optional string` MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs. - `url: optional string` Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*. - `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. - `resolution: optional "1k" or "2k"` Output resolution for every extracted layer. 1k is faster and lower cost; 2k re-renders each layer at higher quality (priced higher, per layer). - `"1k"` - `"2k"` - `model: optional Model` 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. - `"uni-1"` - `"uni-1-max"` - `"ray-3.2"` - `output_format: optional "png" or "jpeg"` Output image format - `"png"` - `"jpeg"` - `source: optional ImageRef` 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. - `data: optional string` Base64-encoded image or video data - `file_id: optional string` UUID of a file previously uploaded via POST /files. Skips URL fetch / base64 decode and reuses the file's pre-moderated backing artifact. The referenced file must be owned by the same client and in state=ready. See the Files API for the upload flow. - `generation_id: optional string` UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension. - `media_type: optional string` MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs. - `url: optional string` Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*. - `style: optional "auto" or "manga"` Style preset (auto, manga) - `"auto"` - `"manga"` - `type: optional "image" or "image_edit" or "video" or 3 more` The kind of generation to perform - `"image"` - `"image_edit"` - `"video"` - `"video_edit"` - `"video_reframe"` - `"layering"` - `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 VideoOptions` 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`. - `duration: optional VideoDuration` Video duration - `"5s"` - `"10s"` - `edit: optional VideoEditOptions` Ray 3.2 video-to-video edit controls. Only valid under `video.edit` when `type` is `video_edit`. The source video must be 18 seconds or shorter; output duration matches the source. - `auto_controls: optional boolean` When true, the model derives the control schedule from the source video. When omitted, supplying strength or controls implies manual mode. - `controls: optional AdvancedControls` Per-signal manual conditioning controls for video edits - `depth: optional DepthControl` Depth / scene-geometry conditioning control - `blur: optional number` Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom. - `enabled: optional boolean` Enable or disable depth conditioning. Omit to use the model default. - `face: optional FaceControl` Face-identity conditioning control - `enabled: optional boolean` Enable or disable face conditioning. Omit to use the model default. - `normals: optional NormalsControl` Surface-normals conditioning control - `augmentation: optional number` Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry. - `enabled: optional boolean` Enable or disable normals conditioning. Omit to use the model default. - `pose: optional PoseControl` Pose / skeleton conditioning control - `enabled: optional boolean` Enable or disable pose conditioning. Omit to use the model default. - `strength: optional PoseControlStrength` Pose-conditioning strength - `"precise"` - `"coarse"` - `trajectory: optional TrajectoryControl` Motion-trajectory conditioning control - `enabled: optional boolean` Enable or disable trajectory conditioning. Omit to use the model default. - `sparsity: optional number` Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors. - `keyframe_indexes: optional array of number` Parallel list of non-negative, unique frame positions in the source video's frame grid where each keyframes[i] is anchored. Must match keyframes in length. - `keyframes: optional array of ImageRef` Multi-anchor guide-frame images at arbitrary source-frame positions (parallel with keyframe_indexes). Up to 64 anchors. Mutually exclusive with video.start_frame (the single-anchor case). Each entry takes the same ImageRef shape as source / image_ref[]. - `data: optional string` Base64-encoded image or video data - `file_id: optional string` UUID of a file previously uploaded via POST /files. Skips URL fetch / base64 decode and reuses the file's pre-moderated backing artifact. The referenced file must be owned by the same client and in state=ready. See the Files API for the upload flow. - `generation_id: optional string` UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension. - `media_type: optional string` MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs. - `url: optional string` Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*. - `strength: optional VideoEditStrength` How much a video edit preserves or reimagines the source - `"adhere_1"` - `"adhere_2"` - `"adhere_3"` - `"flex_1"` - `"flex_2"` - `"flex_3"` - `"reimagine_1"` - `"reimagine_2"` - `"reimagine_3"` - `end_frame: optional ImageRef` 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. - `exr_export: optional boolean` Export EXR alongside the MP4. Requires hdr=true. - `guide_frame: optional ImageRef` 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. - `hdr: optional boolean` Generate HDR video. Requires HDR access. Not supported for video_reframe. - `keyframe_indexes: optional array of number` Parallel list of non-negative, unique output-frame positions where each keyframes[i] is anchored, in the duration x 24fps grid (5s -> 0..120, 10s -> 0..240). Must match keyframes in length. - `keyframes: optional array of ImageRef` Image-to-video guide frames (type=video only), each pinned to an output-frame position via the parallel keyframe_indexes. 1-64 anchors: a single anchor is a valid start-pinned i2v (an alternate to start_frame), and any count up to 64 places guide frames at arbitrary positions. Unlike start_frame/end_frame (the legacy 2-frame surface), this supports arbitrary positions, 10s durations, and HDR. Mutually exclusive with start_frame / end_frame / loop. Only supported on model ray-3.2. For video-to-video keyframes use video.edit.keyframes on type=video_edit instead. - `data: optional string` Base64-encoded image or video data - `file_id: optional string` UUID of a file previously uploaded via POST /files. Skips URL fetch / base64 decode and reuses the file's pre-moderated backing artifact. The referenced file must be owned by the same client and in state=ready. See the Files API for the upload flow. - `generation_id: optional string` UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension. - `media_type: optional string` MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs. - `url: optional string` Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*. - `loop: optional boolean` Generate a seamlessly looping video. Only valid for type=video; not supported with duration=10s or hdr=true. - `resolution: optional VideoResolution` Ray 3.2 video output resolution. 360p is the draft tier (fast, low-cost previews), accepted on type=video, video_edit, and video_reframe; on type=video it is SDR-only (not valid with hdr=true). 1080p is public for video generation; video_reframe 1080p is still rolling out and may return a coming-soon validation error until enabled for the caller. - `"360p"` - `"540p"` - `"720p"` - `"1080p"` - `source_position: optional SourcePosition` Normalized source rectangle inside the output canvas for video_reframe. Omit to let the model choose the default centered-fit crop. - `h_norm: number` Source rectangle height, as a fraction of canvas height. Up to 2.0 so the source can bleed off-canvas. - `w_norm: number` Source rectangle width, as a fraction of canvas width. Up to 2.0 so the source can bleed off-canvas. - `x_norm: number` Left edge of the source rectangle, as a fraction of canvas width. May be negative when the source extends off-canvas. - `y_norm: number` Top edge of the source rectangle, as a fraction of canvas height. May be negative when the source extends off-canvas. - `start_frame: optional ImageRef` 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. - `web_search: optional boolean` Enable web search grounding — the agent can search the web and download reference images before generating. ### Returns - `Generation = object { id, created_at, model, 5 more }` Generation status and output - `id: string` Generation identifier - `created_at: string` Creation timestamp - `model: Model` 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 GenerationFailureCode` 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` 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 ### Example ```http curl https://agents.lumalabs.ai/v1/generations \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \ -d '{ "prompt": "A glass of iced coffee on a marble countertop, morning light streaming through a window" }' ``` #### Response ```json { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "created_at": "created_at", "model": "uni-1", "state": "queued", "type": "image", "failure_code": "content_moderated", "failure_reason": "failure_reason", "output": [ { "type": "type", "url": "https://example.com", "layer": { "alpha_hint": "alpha_hint", "description": "description", "index": 0, "label": "label", "bounds": { "canvas_height": 0, "canvas_width": 0, "height": 0, "width": 0, "x": 0, "y": 0 } } } ] } ``` ## Get a generation **get** `/generations/{generation_id}` Poll for generation status and output. On completion, the response includes presigned URLs to download the generated images. ### Path Parameters - `generation_id: string` ### Returns - `Generation = object { id, created_at, model, 5 more }` Generation status and output - `id: string` Generation identifier - `created_at: string` Creation timestamp - `model: Model` 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 GenerationFailureCode` 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` 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 ### Example ```http curl https://agents.lumalabs.ai/v1/generations/$GENERATION_ID \ -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" ``` #### Response ```json { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "created_at": "created_at", "model": "uni-1", "state": "queued", "type": "image", "failure_code": "content_moderated", "failure_reason": "failure_reason", "output": [ { "type": "type", "url": "https://example.com", "layer": { "alpha_hint": "alpha_hint", "description": "description", "index": 0, "label": "label", "bounds": { "canvas_height": 0, "canvas_width": 0, "height": 0, "width": 0, "x": 0, "y": 0 } } } ] } ``` ## Domain Types ### Advanced Controls - `AdvancedControls = object { depth, face, normals, 2 more }` Per-signal manual conditioning controls for video edits - `depth: optional DepthControl` Depth / scene-geometry conditioning control - `blur: optional number` Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom. - `enabled: optional boolean` Enable or disable depth conditioning. Omit to use the model default. - `face: optional FaceControl` Face-identity conditioning control - `enabled: optional boolean` Enable or disable face conditioning. Omit to use the model default. - `normals: optional NormalsControl` Surface-normals conditioning control - `augmentation: optional number` Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry. - `enabled: optional boolean` Enable or disable normals conditioning. Omit to use the model default. - `pose: optional PoseControl` Pose / skeleton conditioning control - `enabled: optional boolean` Enable or disable pose conditioning. Omit to use the model default. - `strength: optional PoseControlStrength` Pose-conditioning strength - `"precise"` - `"coarse"` - `trajectory: optional TrajectoryControl` Motion-trajectory conditioning control - `enabled: optional boolean` Enable or disable trajectory conditioning. Omit to use the model default. - `sparsity: optional number` Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors. ### Depth Control - `DepthControl = object { blur, enabled }` Depth / scene-geometry conditioning control - `blur: optional number` Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom. - `enabled: optional boolean` Enable or disable depth conditioning. Omit to use the model default. ### Face Control - `FaceControl = object { enabled }` Face-identity conditioning control - `enabled: optional boolean` Enable or disable face conditioning. Omit to use the model default. ### Generation - `Generation = object { id, created_at, model, 5 more }` Generation status and output - `id: string` Generation identifier - `created_at: string` Creation timestamp - `model: Model` 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 GenerationFailureCode` 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` 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 ### Generation Failure Code - `GenerationFailureCode = "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"` ### Generation Output - `GenerationOutput = object { type, url, layer }` A single generated output - `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 ### Image Ref - `ImageRef = 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. - `data: optional string` Base64-encoded image or video data - `file_id: optional string` UUID of a file previously uploaded via POST /files. Skips URL fetch / base64 decode and reuses the file's pre-moderated backing artifact. The referenced file must be owned by the same client and in state=ready. See the Files API for the upload flow. - `generation_id: optional string` UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension. - `media_type: optional string` MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs. - `url: optional string` Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*. ### Model - `Model = "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. - `"uni-1"` - `"uni-1-max"` - `"ray-3.2"` ### Normals Control - `NormalsControl = object { augmentation, enabled }` Surface-normals conditioning control - `augmentation: optional number` Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry. - `enabled: optional boolean` Enable or disable normals conditioning. Omit to use the model default. ### Pose Control - `PoseControl = object { enabled, strength }` Pose / skeleton conditioning control - `enabled: optional boolean` Enable or disable pose conditioning. Omit to use the model default. - `strength: optional PoseControlStrength` Pose-conditioning strength - `"precise"` - `"coarse"` ### Pose Control Strength - `PoseControlStrength = "precise" or "coarse"` Pose-conditioning strength - `"precise"` - `"coarse"` ### Source Position - `SourcePosition = object { h_norm, w_norm, x_norm, y_norm }` Normalized source rectangle inside the output canvas for video_reframe. Omit to let the model choose the default centered-fit crop. - `h_norm: number` Source rectangle height, as a fraction of canvas height. Up to 2.0 so the source can bleed off-canvas. - `w_norm: number` Source rectangle width, as a fraction of canvas width. Up to 2.0 so the source can bleed off-canvas. - `x_norm: number` Left edge of the source rectangle, as a fraction of canvas width. May be negative when the source extends off-canvas. - `y_norm: number` Top edge of the source rectangle, as a fraction of canvas height. May be negative when the source extends off-canvas. ### Trajectory Control - `TrajectoryControl = object { enabled, sparsity }` Motion-trajectory conditioning control - `enabled: optional boolean` Enable or disable trajectory conditioning. Omit to use the model default. - `sparsity: optional number` Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors. ### Video Duration - `VideoDuration = "5s" or "10s"` Video duration - `"5s"` - `"10s"` ### Video Edit Options - `VideoEditOptions = object { auto_controls, controls, keyframe_indexes, 2 more }` Ray 3.2 video-to-video edit controls. Only valid under `video.edit` when `type` is `video_edit`. The source video must be 18 seconds or shorter; output duration matches the source. - `auto_controls: optional boolean` When true, the model derives the control schedule from the source video. When omitted, supplying strength or controls implies manual mode. - `controls: optional AdvancedControls` Per-signal manual conditioning controls for video edits - `depth: optional DepthControl` Depth / scene-geometry conditioning control - `blur: optional number` Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom. - `enabled: optional boolean` Enable or disable depth conditioning. Omit to use the model default. - `face: optional FaceControl` Face-identity conditioning control - `enabled: optional boolean` Enable or disable face conditioning. Omit to use the model default. - `normals: optional NormalsControl` Surface-normals conditioning control - `augmentation: optional number` Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry. - `enabled: optional boolean` Enable or disable normals conditioning. Omit to use the model default. - `pose: optional PoseControl` Pose / skeleton conditioning control - `enabled: optional boolean` Enable or disable pose conditioning. Omit to use the model default. - `strength: optional PoseControlStrength` Pose-conditioning strength - `"precise"` - `"coarse"` - `trajectory: optional TrajectoryControl` Motion-trajectory conditioning control - `enabled: optional boolean` Enable or disable trajectory conditioning. Omit to use the model default. - `sparsity: optional number` Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors. - `keyframe_indexes: optional array of number` Parallel list of non-negative, unique frame positions in the source video's frame grid where each keyframes[i] is anchored. Must match keyframes in length. - `keyframes: optional array of ImageRef` Multi-anchor guide-frame images at arbitrary source-frame positions (parallel with keyframe_indexes). Up to 64 anchors. Mutually exclusive with video.start_frame (the single-anchor case). Each entry takes the same ImageRef shape as source / image_ref[]. - `data: optional string` Base64-encoded image or video data - `file_id: optional string` UUID of a file previously uploaded via POST /files. Skips URL fetch / base64 decode and reuses the file's pre-moderated backing artifact. The referenced file must be owned by the same client and in state=ready. See the Files API for the upload flow. - `generation_id: optional string` UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension. - `media_type: optional string` MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs. - `url: optional string` Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*. - `strength: optional VideoEditStrength` How much a video edit preserves or reimagines the source - `"adhere_1"` - `"adhere_2"` - `"adhere_3"` - `"flex_1"` - `"flex_2"` - `"flex_3"` - `"reimagine_1"` - `"reimagine_2"` - `"reimagine_3"` ### Video Edit Strength - `VideoEditStrength = "adhere_1" or "adhere_2" or "adhere_3" or 6 more` How much a video edit preserves or reimagines the source - `"adhere_1"` - `"adhere_2"` - `"adhere_3"` - `"flex_1"` - `"flex_2"` - `"flex_3"` - `"reimagine_1"` - `"reimagine_2"` - `"reimagine_3"` ### Video Options - `VideoOptions = 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`. - `duration: optional VideoDuration` Video duration - `"5s"` - `"10s"` - `edit: optional VideoEditOptions` Ray 3.2 video-to-video edit controls. Only valid under `video.edit` when `type` is `video_edit`. The source video must be 18 seconds or shorter; output duration matches the source. - `auto_controls: optional boolean` When true, the model derives the control schedule from the source video. When omitted, supplying strength or controls implies manual mode. - `controls: optional AdvancedControls` Per-signal manual conditioning controls for video edits - `depth: optional DepthControl` Depth / scene-geometry conditioning control - `blur: optional number` Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom. - `enabled: optional boolean` Enable or disable depth conditioning. Omit to use the model default. - `face: optional FaceControl` Face-identity conditioning control - `enabled: optional boolean` Enable or disable face conditioning. Omit to use the model default. - `normals: optional NormalsControl` Surface-normals conditioning control - `augmentation: optional number` Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry. - `enabled: optional boolean` Enable or disable normals conditioning. Omit to use the model default. - `pose: optional PoseControl` Pose / skeleton conditioning control - `enabled: optional boolean` Enable or disable pose conditioning. Omit to use the model default. - `strength: optional PoseControlStrength` Pose-conditioning strength - `"precise"` - `"coarse"` - `trajectory: optional TrajectoryControl` Motion-trajectory conditioning control - `enabled: optional boolean` Enable or disable trajectory conditioning. Omit to use the model default. - `sparsity: optional number` Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors. - `keyframe_indexes: optional array of number` Parallel list of non-negative, unique frame positions in the source video's frame grid where each keyframes[i] is anchored. Must match keyframes in length. - `keyframes: optional array of ImageRef` Multi-anchor guide-frame images at arbitrary source-frame positions (parallel with keyframe_indexes). Up to 64 anchors. Mutually exclusive with video.start_frame (the single-anchor case). Each entry takes the same ImageRef shape as source / image_ref[]. - `data: optional string` Base64-encoded image or video data - `file_id: optional string` UUID of a file previously uploaded via POST /files. Skips URL fetch / base64 decode and reuses the file's pre-moderated backing artifact. The referenced file must be owned by the same client and in state=ready. See the Files API for the upload flow. - `generation_id: optional string` UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension. - `media_type: optional string` MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs. - `url: optional string` Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*. - `strength: optional VideoEditStrength` How much a video edit preserves or reimagines the source - `"adhere_1"` - `"adhere_2"` - `"adhere_3"` - `"flex_1"` - `"flex_2"` - `"flex_3"` - `"reimagine_1"` - `"reimagine_2"` - `"reimagine_3"` - `end_frame: optional ImageRef` 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. - `data: optional string` Base64-encoded image or video data - `file_id: optional string` UUID of a file previously uploaded via POST /files. Skips URL fetch / base64 decode and reuses the file's pre-moderated backing artifact. The referenced file must be owned by the same client and in state=ready. See the Files API for the upload flow. - `generation_id: optional string` UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension. - `media_type: optional string` MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs. - `url: optional string` Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*. - `exr_export: optional boolean` Export EXR alongside the MP4. Requires hdr=true. - `guide_frame: optional ImageRef` 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. - `hdr: optional boolean` Generate HDR video. Requires HDR access. Not supported for video_reframe. - `keyframe_indexes: optional array of number` Parallel list of non-negative, unique output-frame positions where each keyframes[i] is anchored, in the duration x 24fps grid (5s -> 0..120, 10s -> 0..240). Must match keyframes in length. - `keyframes: optional array of ImageRef` Image-to-video guide frames (type=video only), each pinned to an output-frame position via the parallel keyframe_indexes. 1-64 anchors: a single anchor is a valid start-pinned i2v (an alternate to start_frame), and any count up to 64 places guide frames at arbitrary positions. Unlike start_frame/end_frame (the legacy 2-frame surface), this supports arbitrary positions, 10s durations, and HDR. Mutually exclusive with start_frame / end_frame / loop. Only supported on model ray-3.2. For video-to-video keyframes use video.edit.keyframes on type=video_edit instead. - `data: optional string` Base64-encoded image or video data - `file_id: optional string` UUID of a file previously uploaded via POST /files. Skips URL fetch / base64 decode and reuses the file's pre-moderated backing artifact. The referenced file must be owned by the same client and in state=ready. See the Files API for the upload flow. - `generation_id: optional string` UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension. - `media_type: optional string` MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs. - `url: optional string` Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*. - `loop: optional boolean` Generate a seamlessly looping video. Only valid for type=video; not supported with duration=10s or hdr=true. - `resolution: optional VideoResolution` Ray 3.2 video output resolution. 360p is the draft tier (fast, low-cost previews), accepted on type=video, video_edit, and video_reframe; on type=video it is SDR-only (not valid with hdr=true). 1080p is public for video generation; video_reframe 1080p is still rolling out and may return a coming-soon validation error until enabled for the caller. - `"360p"` - `"540p"` - `"720p"` - `"1080p"` - `source_position: optional SourcePosition` Normalized source rectangle inside the output canvas for video_reframe. Omit to let the model choose the default centered-fit crop. - `h_norm: number` Source rectangle height, as a fraction of canvas height. Up to 2.0 so the source can bleed off-canvas. - `w_norm: number` Source rectangle width, as a fraction of canvas width. Up to 2.0 so the source can bleed off-canvas. - `x_norm: number` Left edge of the source rectangle, as a fraction of canvas width. May be negative when the source extends off-canvas. - `y_norm: number` Top edge of the source rectangle, as a fraction of canvas height. May be negative when the source extends off-canvas. - `start_frame: optional ImageRef` 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. ### Video Resolution - `VideoResolution = "360p" or "540p" or "720p" or "1080p"` Ray 3.2 video output resolution. 360p is the draft tier (fast, low-cost previews), accepted on type=video, video_edit, and video_reframe; on type=video it is SDR-only (not valid with hdr=true). 1080p is public for video generation; video_reframe 1080p is still rolling out and may return a coming-soon validation error until enabled for the caller. - `"360p"` - `"540p"` - `"720p"` - `"1080p"`