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}.

Parameters

body GenerationNewParams

Prompt param.Field[string]

Text prompt

maxLength: 6000

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 GenerationNewParamsAspectRatio4_5 GenerationNewParamsAspectRatio = "4:5"

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

Layering param.Field[GenerationNewParamsLayering]

optional

Layering options. Applies only to type=layering; rejected on every other type. The image to split goes in source, and prompt may carry optional guidance for how to split it (up to 500 characters, may be empty). Unknown keys are rejected rather than ignored.

Resolution GenerationNewParamsLayeringResolution

optional

Output resolution for every layer. 2k re-renders each layer at higher quality and costs more; either is one flat price per generation, whatever the number of layers.

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.

maxLength: 256

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.

Returns

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