Generations

Create a generation

client.Generations.New(ctx, body) (*Generation, error)

POST/generations

Get a generation

client.Generations.Get(ctx, generationID) (*Generation, error)

GET/generations/{generation_id}

ModelsExpandCollapse

type AdvancedControls struct{…}

Per-signal manual conditioning controls for video edits

Depth DepthControl

optional

Depth / scene-geometry conditioning control

Blur float64

optional

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

format: float, minimum: 0, maximum: 1

Enabled bool

optional

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

Face FaceControl

optional

Face-identity conditioning control

Enabled bool

optional

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

Normals NormalsControl

optional

Surface-normals conditioning control

Augmentation float64

optional

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

format: float, minimum: 0, maximum: 1

Enabled bool

optional

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

Pose PoseControl

optional

Pose / skeleton conditioning control

Enabled bool

optional

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

Strength PoseControlStrength

optional

Pose-conditioning strength

One of the following:

const PoseControlStrengthPrecise PoseControlStrength = "precise"

const PoseControlStrengthCoarse PoseControlStrength = "coarse"

Trajectory TrajectoryControl

optional

Motion-trajectory conditioning control

Enabled bool

optional

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

Sparsity float64

optional

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

format: float, minimum: 0, maximum: 1

type DepthControl struct{…}

Depth / scene-geometry conditioning control

Blur float64

optional

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

format: float, minimum: 0, maximum: 1

Enabled bool

optional

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

type FaceControl struct{…}

Face-identity conditioning control

Enabled bool

optional

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

type Generation struct{…}

Generation status and output

ID string

Generation identifier

format: uuid

CreatedAt string

Creation timestamp

Model Model

Model used

One of the following:

const ModelUni1 Model = "uni-1"

const ModelUni1Max Model = "uni-1-max"

const ModelRay3_2 Model = "ray-3.2"

State GenerationState

Current state of the generation

One of the following:

const GenerationStateQueued GenerationState = "queued"

const GenerationStateProcessing GenerationState = "processing"

const GenerationStateCompleted GenerationState = "completed"

const GenerationStateFailed GenerationState = "failed"

Type GenerationType

The kind of generation to perform

One of the following:

const GenerationTypeImage GenerationType = "image"

const GenerationTypeImageEdit GenerationType = "image_edit"

const GenerationTypeVideo GenerationType = "video"

const GenerationTypeVideoEdit GenerationType = "video_edit"

const GenerationTypeVideoReframe GenerationType = "video_reframe"

const GenerationTypeLayering GenerationType = "layering"

FailureCode GenerationFailureCode

optional

Machine-readable failure code for programmatic handling

One of the following:

const GenerationFailureCodeContentModerated GenerationFailureCode = "content_moderated"

const GenerationFailureCodeGenerationFailed GenerationFailureCode = "generation_failed"

const GenerationFailureCodeBudgetExhausted GenerationFailureCode = "budget_exhausted"

const GenerationFailureCodeOutputNotFound GenerationFailureCode = "output_not_found"

const GenerationFailureCodeImageTooLarge GenerationFailureCode = "image_too_large"

const GenerationFailureCodeUnsupportedFormat GenerationFailureCode = "unsupported_format"

const GenerationFailureCodeCorruptInput GenerationFailureCode = "corrupt_input"

const GenerationFailureCodeInvalidRequest GenerationFailureCode = "invalid_request"

const GenerationFailureCodeRateLimited GenerationFailureCode = "rate_limited"

FailureReason string

optional

Human-readable failure description

Output []GenerationOutput

optional

Generated outputs (populated on completion)

Type string

Media type (e.g. image, video)

URL string

Presigned URL (1hr expiry)

format: uri

Layer GenerationOutputLayer

optional

Per-layer semantics for a type=layering output

AlphaHint 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 int64

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

Label string

Short (1-2 word) layer name

Bounds GenerationOutputLayerBounds

optional

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.

CanvasHeight int64

Height of the full composite canvas the layers reassemble into

CanvasWidth int64

Width of the full composite canvas the layers reassemble into

Height int64

Pixel height of the returned layer image

Width int64

Pixel width of the returned layer image

X int64

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

Y int64

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

ContainsText bool

optional

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 GenerationOutputLayerText

optional

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 string

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

Decorated bool

optional

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

Font GenerationOutputLayerTextFont

optional

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

Category GenerationOutputLayerTextFontCategory

Letterform style

One of the following:

const GenerationOutputLayerTextFontCategorySansSerif GenerationOutputLayerTextFontCategory = "sans serif"

const GenerationOutputLayerTextFontCategorySerif GenerationOutputLayerTextFontCategory = "serif"

const GenerationOutputLayerTextFontCategorySlabSerif GenerationOutputLayerTextFontCategory = "slab serif"

const GenerationOutputLayerTextFontCategoryDisplaySans GenerationOutputLayerTextFontCategory = "display sans"

const GenerationOutputLayerTextFontCategoryDisplaySerif GenerationOutputLayerTextFontCategory = "display serif"

const GenerationOutputLayerTextFontCategoryDisplaySlab GenerationOutputLayerTextFontCategory = "display slab"

const GenerationOutputLayerTextFontCategoryDisplayDecorative GenerationOutputLayerTextFontCategory = "display decorative"

const GenerationOutputLayerTextFontCategoryHandwriting GenerationOutputLayerTextFontCategory = "handwriting"

const GenerationOutputLayerTextFontCategoryMonospace GenerationOutputLayerTextFontCategory = "monospace"

Families []string

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 GenerationOutputLayerTextFontWeight

Stroke weight

One of the following:

const GenerationOutputLayerTextFontWeightThin GenerationOutputLayerTextFontWeight = "thin"

const GenerationOutputLayerTextFontWeightLight GenerationOutputLayerTextFontWeight = "light"

const GenerationOutputLayerTextFontWeightRegular GenerationOutputLayerTextFontWeight = "regular"

const GenerationOutputLayerTextFontWeightMedium GenerationOutputLayerTextFontWeight = "medium"

const GenerationOutputLayerTextFontWeightBold GenerationOutputLayerTextFontWeight = "bold"

const GenerationOutputLayerTextFontWeightBlack GenerationOutputLayerTextFontWeight = "black"

Width GenerationOutputLayerTextFontWidth

Letter width for its height

One of the following:

const GenerationOutputLayerTextFontWidthCondensed GenerationOutputLayerTextFontWidth = "condensed"

const GenerationOutputLayerTextFontWidthNormal GenerationOutputLayerTextFontWidth = "normal"

const GenerationOutputLayerTextFontWidthWide GenerationOutputLayerTextFontWidth = "wide"

Match GenerationOutputLayerTextFontMatch

optional

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.

FaceID string

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

FamilyID string

Typed ref of the matched font family, font_family:

FamilyName string

Name of the matched font family

Style GenerationOutputLayerTextFontMatchStyle

Style of the matched face

One of the following:

const GenerationOutputLayerTextFontMatchStyleNormal GenerationOutputLayerTextFontMatchStyle = "normal"

const GenerationOutputLayerTextFontMatchStyleItalic GenerationOutputLayerTextFontMatchStyle = "italic"

Weight int64

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

Usage GenerationUsage

optional

What one generation actually cost, as billing settled it

CreditsCharged int64

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

type GenerationFailureCode string

Machine-readable failure code for programmatic handling

One of the following:

const GenerationFailureCodeContentModerated GenerationFailureCode = "content_moderated"

const GenerationFailureCodeGenerationFailed GenerationFailureCode = "generation_failed"

const GenerationFailureCodeBudgetExhausted GenerationFailureCode = "budget_exhausted"

const GenerationFailureCodeOutputNotFound GenerationFailureCode = "output_not_found"

const GenerationFailureCodeImageTooLarge GenerationFailureCode = "image_too_large"

const GenerationFailureCodeUnsupportedFormat GenerationFailureCode = "unsupported_format"

const GenerationFailureCodeCorruptInput GenerationFailureCode = "corrupt_input"

const GenerationFailureCodeInvalidRequest GenerationFailureCode = "invalid_request"

const GenerationFailureCodeRateLimited GenerationFailureCode = "rate_limited"

type GenerationOutput struct{…}

A single generated output

Type string

Media type (e.g. image, video)

URL string

Presigned URL (1hr expiry)

format: uri

Layer GenerationOutputLayer

optional

Per-layer semantics for a type=layering output

AlphaHint 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 int64

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

Label string

Short (1-2 word) layer name

Bounds GenerationOutputLayerBounds

optional

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.

CanvasHeight int64

Height of the full composite canvas the layers reassemble into

CanvasWidth int64

Width of the full composite canvas the layers reassemble into

Height int64

Pixel height of the returned layer image

Width int64

Pixel width of the returned layer image

X int64

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

Y int64

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

ContainsText bool

optional

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 GenerationOutputLayerText

optional

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 string

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

Decorated bool

optional

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

Font GenerationOutputLayerTextFont

optional

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

Category GenerationOutputLayerTextFontCategory

Letterform style

One of the following:

const GenerationOutputLayerTextFontCategorySansSerif GenerationOutputLayerTextFontCategory = "sans serif"

const GenerationOutputLayerTextFontCategorySerif GenerationOutputLayerTextFontCategory = "serif"

const GenerationOutputLayerTextFontCategorySlabSerif GenerationOutputLayerTextFontCategory = "slab serif"

const GenerationOutputLayerTextFontCategoryDisplaySans GenerationOutputLayerTextFontCategory = "display sans"

const GenerationOutputLayerTextFontCategoryDisplaySerif GenerationOutputLayerTextFontCategory = "display serif"

const GenerationOutputLayerTextFontCategoryDisplaySlab GenerationOutputLayerTextFontCategory = "display slab"

const GenerationOutputLayerTextFontCategoryDisplayDecorative GenerationOutputLayerTextFontCategory = "display decorative"

const GenerationOutputLayerTextFontCategoryHandwriting GenerationOutputLayerTextFontCategory = "handwriting"

const GenerationOutputLayerTextFontCategoryMonospace GenerationOutputLayerTextFontCategory = "monospace"

Families []string

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 GenerationOutputLayerTextFontWeight

Stroke weight

One of the following:

const GenerationOutputLayerTextFontWeightThin GenerationOutputLayerTextFontWeight = "thin"

const GenerationOutputLayerTextFontWeightLight GenerationOutputLayerTextFontWeight = "light"

const GenerationOutputLayerTextFontWeightRegular GenerationOutputLayerTextFontWeight = "regular"

const GenerationOutputLayerTextFontWeightMedium GenerationOutputLayerTextFontWeight = "medium"

const GenerationOutputLayerTextFontWeightBold GenerationOutputLayerTextFontWeight = "bold"

const GenerationOutputLayerTextFontWeightBlack GenerationOutputLayerTextFontWeight = "black"

Width GenerationOutputLayerTextFontWidth

Letter width for its height

One of the following:

const GenerationOutputLayerTextFontWidthCondensed GenerationOutputLayerTextFontWidth = "condensed"

const GenerationOutputLayerTextFontWidthNormal GenerationOutputLayerTextFontWidth = "normal"

const GenerationOutputLayerTextFontWidthWide GenerationOutputLayerTextFontWidth = "wide"

Match GenerationOutputLayerTextFontMatch

optional

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.

FaceID string

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

FamilyID string

Typed ref of the matched font family, font_family:

FamilyName string

Name of the matched font family

Style GenerationOutputLayerTextFontMatchStyle

Style of the matched face

One of the following:

const GenerationOutputLayerTextFontMatchStyleNormal GenerationOutputLayerTextFontMatchStyle = "normal"

const GenerationOutputLayerTextFontMatchStyleItalic GenerationOutputLayerTextFontMatchStyle = "italic"

Weight int64

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

type GenerationUsage struct{…}

What one generation actually cost, as billing settled it

CreditsCharged int64

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

type ImageRef struct{…}

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 string

optional

Base64-encoded image or video data

FileID string

optional

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

GenerationID string

optional

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

MediaType string

optional

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 string

optional

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

type Model string

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:

const ModelUni1 Model = "uni-1"

const ModelUni1Max Model = "uni-1-max"

const ModelRay3_2 Model = "ray-3.2"

type NormalsControl struct{…}

Surface-normals conditioning control

Augmentation float64

optional

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

format: float, minimum: 0, maximum: 1

Enabled bool

optional

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

type PoseControl struct{…}

Pose / skeleton conditioning control

Enabled bool

optional

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

Strength PoseControlStrength

optional

Pose-conditioning strength

One of the following:

const PoseControlStrengthPrecise PoseControlStrength = "precise"

const PoseControlStrengthCoarse PoseControlStrength = "coarse"

type PoseControlStrength string

Pose-conditioning strength

One of the following:

const PoseControlStrengthPrecise PoseControlStrength = "precise"

const PoseControlStrengthCoarse PoseControlStrength = "coarse"

type SourcePosition struct{…}

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

HNorm float64

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

WNorm float64

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

XNorm float64

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

YNorm float64

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

type TrajectoryControl struct{…}

Motion-trajectory conditioning control

Enabled bool

optional

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

Sparsity float64

optional

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

format: float, minimum: 0, maximum: 1

type VideoDuration string

Video duration

One of the following:

const VideoDuration5s VideoDuration = "5s"

const VideoDuration10s VideoDuration = "10s"

type VideoEditOptions struct{…}

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.

AutoControls bool

optional

When true, the model derives the control schedule from the source video. When omitted, supplying strength or controls implies manual mode.

Controls AdvancedControls

optional

Per-signal manual conditioning controls for video edits

Depth DepthControl

optional

Depth / scene-geometry conditioning control

Blur float64

optional

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

format: float, minimum: 0, maximum: 1

Enabled bool

optional

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

Face FaceControl

optional

Face-identity conditioning control

Enabled bool

optional

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

Normals NormalsControl

optional

Surface-normals conditioning control

Augmentation float64

optional

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

format: float, minimum: 0, maximum: 1

Enabled bool

optional

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

Pose PoseControl

optional

Pose / skeleton conditioning control

Enabled bool

optional

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

Strength PoseControlStrength

optional

Pose-conditioning strength

One of the following:

const PoseControlStrengthPrecise PoseControlStrength = "precise"

const PoseControlStrengthCoarse PoseControlStrength = "coarse"

Trajectory TrajectoryControl

optional

Motion-trajectory conditioning control

Enabled bool

optional

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

Sparsity float64

optional

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

format: float, minimum: 0, maximum: 1

KeyframeIndexes []int64

optional

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

optional

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 string

optional

Base64-encoded image or video data

FileID string

optional

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

GenerationID string

optional

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

MediaType string

optional

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 string

optional

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

Strength VideoEditStrength

optional

How much a video edit preserves or reimagines the source

One of the following:

const VideoEditStrengthAdhere1 VideoEditStrength = "adhere_1"

const VideoEditStrengthAdhere2 VideoEditStrength = "adhere_2"

const VideoEditStrengthAdhere3 VideoEditStrength = "adhere_3"

const VideoEditStrengthFlex1 VideoEditStrength = "flex_1"

const VideoEditStrengthFlex2 VideoEditStrength = "flex_2"

const VideoEditStrengthFlex3 VideoEditStrength = "flex_3"

const VideoEditStrengthReimagine1 VideoEditStrength = "reimagine_1"

const VideoEditStrengthReimagine2 VideoEditStrength = "reimagine_2"

const VideoEditStrengthReimagine3 VideoEditStrength = "reimagine_3"

type VideoEditStrength string

How much a video edit preserves or reimagines the source

One of the following:

const VideoEditStrengthAdhere1 VideoEditStrength = "adhere_1"

const VideoEditStrengthAdhere2 VideoEditStrength = "adhere_2"

const VideoEditStrengthAdhere3 VideoEditStrength = "adhere_3"

const VideoEditStrengthFlex1 VideoEditStrength = "flex_1"

const VideoEditStrengthFlex2 VideoEditStrength = "flex_2"

const VideoEditStrengthFlex3 VideoEditStrength = "flex_3"

const VideoEditStrengthReimagine1 VideoEditStrength = "reimagine_1"

const VideoEditStrengthReimagine2 VideoEditStrength = "reimagine_2"

const VideoEditStrengthReimagine3 VideoEditStrength = "reimagine_3"

type VideoOptions struct{…}

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 VideoDuration

optional

Video duration

One of the following:

const VideoDuration5s VideoDuration = "5s"

const VideoDuration10s VideoDuration = "10s"

Edit VideoEditOptions

optional

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.

AutoControls bool

optional

When true, the model derives the control schedule from the source video. When omitted, supplying strength or controls implies manual mode.

Controls AdvancedControls

optional

Per-signal manual conditioning controls for video edits

Depth DepthControl

optional

Depth / scene-geometry conditioning control

Blur float64

optional

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

format: float, minimum: 0, maximum: 1

Enabled bool

optional

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

Face FaceControl

optional

Face-identity conditioning control

Enabled bool

optional

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

Normals NormalsControl

optional

Surface-normals conditioning control

Augmentation float64

optional

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

format: float, minimum: 0, maximum: 1

Enabled bool

optional

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

Pose PoseControl

optional

Pose / skeleton conditioning control

Enabled bool

optional

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

Strength PoseControlStrength

optional

Pose-conditioning strength

One of the following:

const PoseControlStrengthPrecise PoseControlStrength = "precise"

const PoseControlStrengthCoarse PoseControlStrength = "coarse"

Trajectory TrajectoryControl

optional

Motion-trajectory conditioning control

Enabled bool

optional

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

Sparsity float64

optional

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

format: float, minimum: 0, maximum: 1

KeyframeIndexes []int64

optional

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

optional

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 string

optional

Base64-encoded image or video data

FileID string

optional

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

GenerationID string

optional

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

MediaType string

optional

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 string

optional

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

Strength VideoEditStrength

optional

How much a video edit preserves or reimagines the source

One of the following:

const VideoEditStrengthAdhere1 VideoEditStrength = "adhere_1"

const VideoEditStrengthAdhere2 VideoEditStrength = "adhere_2"

const VideoEditStrengthAdhere3 VideoEditStrength = "adhere_3"

const VideoEditStrengthFlex1 VideoEditStrength = "flex_1"

const VideoEditStrengthFlex2 VideoEditStrength = "flex_2"

const VideoEditStrengthFlex3 VideoEditStrength = "flex_3"

const VideoEditStrengthReimagine1 VideoEditStrength = "reimagine_1"

const VideoEditStrengthReimagine2 VideoEditStrength = "reimagine_2"

const VideoEditStrengthReimagine3 VideoEditStrength = "reimagine_3"

EndFrame ImageRef

optional

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 string

optional

Base64-encoded image or video data

FileID string

optional

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

GenerationID string

optional

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

MediaType string

optional

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 string

optional

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

ExrExport bool

optional

Export EXR alongside the MP4. Requires hdr=true.

GuideFrame ImageRef

optional

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 string

optional

Base64-encoded image or video data

FileID string

optional

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

GenerationID string

optional

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

MediaType string

optional

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 string

optional

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

Hdr bool

optional

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

KeyframeIndexes []int64

optional

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

optional

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 string

optional

Base64-encoded image or video data

FileID string

optional

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

GenerationID string

optional

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

MediaType string

optional

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 string

optional

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

Loop bool

optional

Generate a seamlessly looping video. Only valid for type=video; not supported with duration=10s or hdr=true.

Resolution VideoResolution

optional

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:

const VideoResolution360p VideoResolution = "360p"

const VideoResolution540p VideoResolution = "540p"

const VideoResolution720p VideoResolution = "720p"

const VideoResolution1080p VideoResolution = "1080p"

SourcePosition SourcePosition

optional

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

HNorm float64

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

WNorm float64

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

XNorm float64

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

YNorm float64

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

StartFrame ImageRef

optional

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 string

optional

Base64-encoded image or video data

FileID string

optional

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

GenerationID string

optional

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

MediaType string

optional

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 string

optional

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

type VideoResolution string

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:

const VideoResolution360p VideoResolution = "360p"

const VideoResolution540p VideoResolution = "540p"

const VideoResolution720p VideoResolution = "720p"

const VideoResolution1080p VideoResolution = "1080p"