API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Generations

Create a generation

$ luma-agents-cli generations create

POST/generations

Get a generation

$ luma-agents-cli generations get

GET/generations/{generation_id}

ModelsExpand Collapse

advanced_controls: object { depth, face, normals, 2 more }

Per-signal manual conditioning controls for video edits

depth: optional 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: optional object { enabled }

Face-identity conditioning control

enabled: optional boolean

Enable or disable face conditioning. Omit to use the model default.

normals: optional 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: optional object { enabled, strength }

Pose / skeleton conditioning control

enabled: optional boolean

Enable or disable pose conditioning. Omit to use the model default.

strength: optional "precise" or "coarse"

Pose-conditioning strength

"precise"

"coarse"

trajectory: optional 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.

depth_control: 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: object { enabled }

Face-identity conditioning control

enabled: optional boolean

Enable or disable face conditioning. Omit to use the model default.

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

generation_failure_code: "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: 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: 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: "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: 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: object { enabled, strength }

Pose / skeleton conditioning control

enabled: optional boolean

Enable or disable pose conditioning. Omit to use the model default.

strength: optional "precise" or "coarse"

Pose-conditioning strength

"precise"

"coarse"

pose_control_strength: "precise" or "coarse"

Pose-conditioning strength

"precise"

"coarse"

source_position: 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: 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: "5s" or "10s"

Video duration

"5s"

"10s"

video_edit_options: 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 object { depth, face, normals, 2 more }

Per-signal manual conditioning controls for video edits

depth: optional 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: optional object { enabled }

Face-identity conditioning control

enabled: optional boolean

Enable or disable face conditioning. Omit to use the model default.

normals: optional 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: optional object { enabled, strength }

Pose / skeleton conditioning control

enabled: optional boolean

Enable or disable pose conditioning. Omit to use the model default.

strength: optional "precise" or "coarse"

Pose-conditioning strength

"precise"

"coarse"

trajectory: optional 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.

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 { data, file_id, generation_id, 2 more }

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 "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_edit_strength: "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: 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 "5s" or "10s"

Video duration

"5s"

"10s"

edit: optional 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 object { depth, face, normals, 2 more }

Per-signal manual conditioning controls for video edits

depth: optional 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: optional object { enabled }

Face-identity conditioning control

enabled: optional boolean

Enable or disable face conditioning. Omit to use the model default.

normals: optional 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: optional object { enabled, strength }

Pose / skeleton conditioning control

enabled: optional boolean

Enable or disable pose conditioning. Omit to use the model default.

strength: optional "precise" or "coarse"

Pose-conditioning strength

"precise"

"coarse"

trajectory: optional 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.

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 { data, file_id, generation_id, 2 more }

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 "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"

end_frame: 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.

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 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/*.

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 { data, file_id, generation_id, 2 more }

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 "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"

source_position: optional 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.

start_frame: 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.

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/*.

video_resolution: "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"