Create a generation

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

POST/generations

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

ParametersExpand Collapse

body GenerationNewParams

Prompt param.Field[string]

Text prompt

maxLength6000

AspectRatio param.Field[GenerationNewParamsAspectRatio]optional

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

const GenerationNewParamsAspectRatio3_1 GenerationNewParamsAspectRatio = "3:1"

const GenerationNewParamsAspectRatio2_1 GenerationNewParamsAspectRatio = "2:1"

const GenerationNewParamsAspectRatio21_9 GenerationNewParamsAspectRatio = "21:9"

const GenerationNewParamsAspectRatio16_9 GenerationNewParamsAspectRatio = "16:9"

const GenerationNewParamsAspectRatio4_3 GenerationNewParamsAspectRatio = "4:3"

const GenerationNewParamsAspectRatio3_2 GenerationNewParamsAspectRatio = "3:2"

const GenerationNewParamsAspectRatio1_1 GenerationNewParamsAspectRatio = "1:1"

const GenerationNewParamsAspectRatio3_4 GenerationNewParamsAspectRatio = "3:4"

const GenerationNewParamsAspectRatio2_3 GenerationNewParamsAspectRatio = "2:3"

const GenerationNewParamsAspectRatio9_16 GenerationNewParamsAspectRatio = "9:16"

const GenerationNewParamsAspectRatio1_2 GenerationNewParamsAspectRatio = "1:2"

const GenerationNewParamsAspectRatio1_3 GenerationNewParamsAspectRatio = "1:3"

ImageRef param.Field[[]ImageRef]optional

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

Data stringoptional

Base64-encoded image or video data

FileID stringoptional

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.

formatuuid

GenerationID stringoptional

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.

formatuuid

MediaType stringoptional

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 stringoptional

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

Layering param.Field[GenerationNewParamsLayering]optional

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

Resolution GenerationNewParamsLayeringResolutionoptional

Output resolution for every extracted layer. 1k is faster and lower cost; 2k re-renders each layer at higher quality (priced higher, per layer).

One of the following:

const GenerationNewParamsLayeringResolution1k GenerationNewParamsLayeringResolution = "1k"

const GenerationNewParamsLayeringResolution2k GenerationNewParamsLayeringResolution = "2k"

Model param.Field[Model]optional

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.

OutputFormat param.Field[GenerationNewParamsOutputFormat]optional

Output image format

const GenerationNewParamsOutputFormatPng GenerationNewParamsOutputFormat = "png"

const GenerationNewParamsOutputFormatJpeg GenerationNewParamsOutputFormat = "jpeg"

Source param.Field[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.

Style param.Field[GenerationNewParamsStyle]optional

Style preset (auto, manga)

const GenerationNewParamsStyleAuto GenerationNewParamsStyle = "auto"

const GenerationNewParamsStyleManga GenerationNewParamsStyle = "manga"

Type param.Field[GenerationNewParamsType]optional

The kind of generation to perform

const GenerationNewParamsTypeImage GenerationNewParamsType = "image"

const GenerationNewParamsTypeImageEdit GenerationNewParamsType = "image_edit"

const GenerationNewParamsTypeVideo GenerationNewParamsType = "video"

const GenerationNewParamsTypeVideoEdit GenerationNewParamsType = "video_edit"

const GenerationNewParamsTypeVideoReframe GenerationNewParamsType = "video_reframe"

const GenerationNewParamsTypeLayering GenerationNewParamsType = "layering"

UserID param.Field[string]optional

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

maxLength256

Video param.Field[VideoOptions]optional

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.

WebSearch param.Field[bool]optional

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

ReturnsExpand Collapse

type Generation struct{…}

Generation status and output

ID string

Generation identifier

formatuuid

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 GenerationFailureCodeoptional

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 stringoptional

Human-readable failure description

Output []GenerationOutputoptional

Generated outputs (populated on completion)

Type string

Media type (e.g. image, video)

URL string

Presigned URL (1hr expiry)

formaturi

Layer GenerationOutputLayeroptional

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