Skip to content
Luma Agents
lumalabs.ai
API Reference

Generations

Create a generation
generations.create(**kwargs) -> Generation
POST/generations
Get a generation
generations.get(generation_id) -> Generation
GET/generations/{generation_id}
Models
class AdvancedControls: …

Per-signal manual conditioning controls for video edits

depth: Optional[DepthControl]

Depth / scene-geometry conditioning control

blur: Optional[float]

Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom.

format: float, minimum: 0, maximum: 1
enabled: Optional[bool]

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

face: Optional[FaceControl]

Face-identity conditioning control

enabled: Optional[bool]

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

normals: Optional[NormalsControl]

Surface-normals conditioning control

augmentation: Optional[float]

Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry.

format: float, minimum: 0, maximum: 1
enabled: Optional[bool]

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

pose: Optional[PoseControl]

Pose / skeleton conditioning control

enabled: Optional[bool]

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

strength: Optional[PoseControlStrength]

Pose-conditioning strength

One of the following:
"precise"
"coarse"
trajectory: Optional[TrajectoryControl]

Motion-trajectory conditioning control

enabled: Optional[bool]

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

sparsity: Optional[float]

Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors.

format: float, minimum: 0, maximum: 1
class DepthControl: …

Depth / scene-geometry conditioning control

blur: Optional[float]

Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom.

format: float, minimum: 0, maximum: 1
enabled: Optional[bool]

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

class FaceControl: …

Face-identity conditioning control

enabled: Optional[bool]

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

class Generation: …

Generation status and output

id: str

Generation identifier

format: uuid
created_at: str

Creation timestamp

model: Model

Model used

One of the following:
"uni-1"
"uni-1-max"
"ray-3.2"
state: Literal["queued", "processing", "completed", "failed"]

Current state of the generation

One of the following:
"queued"
"processing"
"completed"
"failed"
type: Literal["image", "image_edit", "video", 3 more]

The kind of generation to perform

One of the following:
"image"
"image_edit"
"video"
"video_edit"
"video_reframe"
"layering"
failure_code: Optional[GenerationFailureCode]

Machine-readable failure code for programmatic handling

One of the following:
"content_moderated"
"generation_failed"
"budget_exhausted"
"output_not_found"
"image_too_large"
"unsupported_format"
"corrupt_input"
"invalid_request"
"rate_limited"
failure_reason: Optional[str]

Human-readable failure description

output: Optional[List[GenerationOutput]]

Generated outputs (populated on completion)

type: str

Media type (e.g. image, video)

url: str

Presigned URL (1hr expiry)

format: uri
layer: Optional[Layer]

Per-layer semantics for a type=layering output

alpha_hint: str

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

description: str

Complete-element caption for the layer's content

index: int

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

label: str

Short (1-2 word) layer name

bounds: Optional[LayerBounds]

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: int

Height of the full composite canvas the layers reassemble into

canvas_width: int

Width of the full composite canvas the layers reassemble into

height: int

Pixel height of the returned layer image

width: int

Pixel width of the returned layer image

x: int

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

y: int

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

contains_text: Optional[bool]

Whether the layer was planned as typeset text (a headline, caption, or label) rather than an image element. Null when not reported for this generation.

text: Optional[LayerText]

The text on one live-text layer, as a string plus how it is styled. Placement is the owning layer's bounds — the text fills that box.

content: str

The text as shown, preserving capitalization; one line per line (newline-separated)

decorated: Optional[bool]

True when the lettering is ornamental (outlines, patterned fills, bevels, drop shadows), so plain typeset text will not reproduce its look.

font: Optional[LayerTextFont]

Described letterform traits of a text layer — enough to pick a matching font.

category: Literal["sans serif", "serif", "slab serif", 6 more]

Letterform style

One of the following:
"sans serif"
"serif"
"slab serif"
"display sans"
"display serif"
"display slab"
"display decorative"
"handwriting"
"monospace"
families: List[str]

Up to three Google Fonts family names that resemble the lettering, closest first. Empty when none of the offered families fit.

italic: bool

Whether the letters are slanted or cursive

weight: Literal["thin", "light", "regular", 3 more]

Stroke weight

One of the following:
"thin"
"light"
"regular"
"medium"
"bold"
"black"
width: Literal["condensed", "normal", "wide"]

Letter width for its height

One of the following:
"condensed"
"normal"
"wide"
match: Optional[LayerTextFontMatch]

The font in your font catalog that the lettering matches, so you can re-set the text in it. Absent when no catalog font matches closely enough, or matching is not enabled. The image itself is not rendered in this font.

face_id: str

Typed ref of the matched face (one weight and style), font_face:

family_id: str

Typed ref of the matched font family, font_family:

family_name: str

Name of the matched font family

style: Literal["normal", "italic"]

Style of the matched face

One of the following:
"normal"
"italic"
weight: int

CSS font weight of the matched face, e.g. 400 or 700

usage: Optional[GenerationUsage]

What one generation actually cost, as billing settled it

credits_charged: int

Credits actually charged for this generation. Null until billing has settled it; a confirmed no-charge outcome is 0. Stays null for a generation whose charge could not be confirmed, including ones settled before this field existed. Never an estimate or the reserved amount.

minimum: 0
Literal["content_moderated", "generation_failed", "budget_exhausted", 6 more]

Machine-readable failure code for programmatic handling

One of the following:
"content_moderated"
"generation_failed"
"budget_exhausted"
"output_not_found"
"image_too_large"
"unsupported_format"
"corrupt_input"
"invalid_request"
"rate_limited"
class GenerationOutput: …

A single generated output

type: str

Media type (e.g. image, video)

url: str

Presigned URL (1hr expiry)

format: uri
layer: Optional[Layer]

Per-layer semantics for a type=layering output

alpha_hint: str

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

description: str

Complete-element caption for the layer's content

index: int

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

label: str

Short (1-2 word) layer name

bounds: Optional[LayerBounds]

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: int

Height of the full composite canvas the layers reassemble into

canvas_width: int

Width of the full composite canvas the layers reassemble into

height: int

Pixel height of the returned layer image

width: int

Pixel width of the returned layer image

x: int

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

y: int

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

contains_text: Optional[bool]

Whether the layer was planned as typeset text (a headline, caption, or label) rather than an image element. Null when not reported for this generation.

text: Optional[LayerText]

The text on one live-text layer, as a string plus how it is styled. Placement is the owning layer's bounds — the text fills that box.

content: str

The text as shown, preserving capitalization; one line per line (newline-separated)

decorated: Optional[bool]

True when the lettering is ornamental (outlines, patterned fills, bevels, drop shadows), so plain typeset text will not reproduce its look.

font: Optional[LayerTextFont]

Described letterform traits of a text layer — enough to pick a matching font.

category: Literal["sans serif", "serif", "slab serif", 6 more]

Letterform style

One of the following:
"sans serif"
"serif"
"slab serif"
"display sans"
"display serif"
"display slab"
"display decorative"
"handwriting"
"monospace"
families: List[str]

Up to three Google Fonts family names that resemble the lettering, closest first. Empty when none of the offered families fit.

italic: bool

Whether the letters are slanted or cursive

weight: Literal["thin", "light", "regular", 3 more]

Stroke weight

One of the following:
"thin"
"light"
"regular"
"medium"
"bold"
"black"
width: Literal["condensed", "normal", "wide"]

Letter width for its height

One of the following:
"condensed"
"normal"
"wide"
match: Optional[LayerTextFontMatch]

The font in your font catalog that the lettering matches, so you can re-set the text in it. Absent when no catalog font matches closely enough, or matching is not enabled. The image itself is not rendered in this font.

face_id: str

Typed ref of the matched face (one weight and style), font_face:

family_id: str

Typed ref of the matched font family, font_family:

family_name: str

Name of the matched font family

style: Literal["normal", "italic"]

Style of the matched face

One of the following:
"normal"
"italic"
weight: int

CSS font weight of the matched face, e.g. 400 or 700

class GenerationUsage: …

What one generation actually cost, as billing settled it

credits_charged: int

Credits actually charged for this generation. Null until billing has settled it; a confirmed no-charge outcome is 0. Stays null for a generation whose charge could not be confirmed, including ones settled before this field existed. Never an estimate or the reserved amount.

minimum: 0
class 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[str]

Base64-encoded image or video data

file_id: Optional[str]

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.

format: uuid
generation_id: Optional[str]

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.

format: uuid
media_type: Optional[str]

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[str]

Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.

Literal["uni-1", "uni-1-max", "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.

One of the following:
"uni-1"
"uni-1-max"
"ray-3.2"
class NormalsControl: …

Surface-normals conditioning control

augmentation: Optional[float]

Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry.

format: float, minimum: 0, maximum: 1
enabled: Optional[bool]

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

class PoseControl: …

Pose / skeleton conditioning control

enabled: Optional[bool]

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

strength: Optional[PoseControlStrength]

Pose-conditioning strength

One of the following:
"precise"
"coarse"
Literal["precise", "coarse"]

Pose-conditioning strength

One of the following:
"precise"
"coarse"
class SourcePosition: …

Normalized source rectangle inside the output canvas for video_reframe. Omit to let the model choose the default centered-fit crop.

h_norm: float

Source rectangle height, as a fraction of canvas height. Up to 2.0 so the source can bleed off-canvas.

format: float, exclusiveMinimum: 0, maximum: 2
w_norm: float

Source rectangle width, as a fraction of canvas width. Up to 2.0 so the source can bleed off-canvas.

format: float, exclusiveMinimum: 0, maximum: 2
x_norm: float

Left edge of the source rectangle, as a fraction of canvas width. May be negative when the source extends off-canvas.

format: float, minimum: -2, maximum: 2
y_norm: float

Top edge of the source rectangle, as a fraction of canvas height. May be negative when the source extends off-canvas.

format: float, minimum: -2, maximum: 2
class TrajectoryControl: …

Motion-trajectory conditioning control

enabled: Optional[bool]

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

sparsity: Optional[float]

Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors.

format: float, minimum: 0, maximum: 1
Literal["5s", "10s"]

Video duration

One of the following:
"5s"
"10s"
class 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[bool]

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[float]

Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom.

format: float, minimum: 0, maximum: 1
enabled: Optional[bool]

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

face: Optional[FaceControl]

Face-identity conditioning control

enabled: Optional[bool]

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

normals: Optional[NormalsControl]

Surface-normals conditioning control

augmentation: Optional[float]

Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry.

format: float, minimum: 0, maximum: 1
enabled: Optional[bool]

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

pose: Optional[PoseControl]

Pose / skeleton conditioning control

enabled: Optional[bool]

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

strength: Optional[PoseControlStrength]

Pose-conditioning strength

One of the following:
"precise"
"coarse"
trajectory: Optional[TrajectoryControl]

Motion-trajectory conditioning control

enabled: Optional[bool]

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

sparsity: Optional[float]

Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors.

format: float, minimum: 0, maximum: 1
keyframe_indexes: Optional[List[int]]

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[List[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[str]

Base64-encoded image or video data

file_id: Optional[str]

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.

format: uuid
generation_id: Optional[str]

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.

format: uuid
media_type: Optional[str]

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[str]

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

One of the following:
"adhere_1"
"adhere_2"
"adhere_3"
"flex_1"
"flex_2"
"flex_3"
"reimagine_1"
"reimagine_2"
"reimagine_3"
Literal["adhere_1", "adhere_2", "adhere_3", 6 more]

How much a video edit preserves or reimagines the source

One of the following:
"adhere_1"
"adhere_2"
"adhere_3"
"flex_1"
"flex_2"
"flex_3"
"reimagine_1"
"reimagine_2"
"reimagine_3"
class 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

One of the following:
"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[bool]

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[float]

Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom.

format: float, minimum: 0, maximum: 1
enabled: Optional[bool]

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

face: Optional[FaceControl]

Face-identity conditioning control

enabled: Optional[bool]

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

normals: Optional[NormalsControl]

Surface-normals conditioning control

augmentation: Optional[float]

Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry.

format: float, minimum: 0, maximum: 1
enabled: Optional[bool]

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

pose: Optional[PoseControl]

Pose / skeleton conditioning control

enabled: Optional[bool]

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

strength: Optional[PoseControlStrength]

Pose-conditioning strength

One of the following:
"precise"
"coarse"
trajectory: Optional[TrajectoryControl]

Motion-trajectory conditioning control

enabled: Optional[bool]

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

sparsity: Optional[float]

Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors.

format: float, minimum: 0, maximum: 1
keyframe_indexes: Optional[List[int]]

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[List[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[str]

Base64-encoded image or video data

file_id: Optional[str]

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.

format: uuid
generation_id: Optional[str]

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.

format: uuid
media_type: Optional[str]

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[str]

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

One of the following:
"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[str]

Base64-encoded image or video data

file_id: Optional[str]

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.

format: uuid
generation_id: Optional[str]

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.

format: uuid
media_type: Optional[str]

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[str]

Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.

exr_export: Optional[bool]

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.

data: Optional[str]

Base64-encoded image or video data

file_id: Optional[str]

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.

format: uuid
generation_id: Optional[str]

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.

format: uuid
media_type: Optional[str]

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[str]

Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.

hdr: Optional[bool]

Generate HDR video. Requires HDR access. Not supported for video_reframe.

keyframe_indexes: Optional[List[int]]

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[List[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[str]

Base64-encoded image or video data

file_id: Optional[str]

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.

format: uuid
generation_id: Optional[str]

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.

format: uuid
media_type: Optional[str]

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[str]

Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.

loop: Optional[bool]

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.

One of the following:
"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: float

Source rectangle height, as a fraction of canvas height. Up to 2.0 so the source can bleed off-canvas.

format: float, exclusiveMinimum: 0, maximum: 2
w_norm: float

Source rectangle width, as a fraction of canvas width. Up to 2.0 so the source can bleed off-canvas.

format: float, exclusiveMinimum: 0, maximum: 2
x_norm: float

Left edge of the source rectangle, as a fraction of canvas width. May be negative when the source extends off-canvas.

format: float, minimum: -2, maximum: 2
y_norm: float

Top edge of the source rectangle, as a fraction of canvas height. May be negative when the source extends off-canvas.

format: float, minimum: -2, maximum: 2
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.

data: Optional[str]

Base64-encoded image or video data

file_id: Optional[str]

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.

format: uuid
generation_id: Optional[str]

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.

format: uuid
media_type: Optional[str]

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[str]

Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.

Literal["360p", "540p", "720p", "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.

One of the following:
"360p"
"540p"
"720p"
"1080p"