Create a generation

generations.create(**kwargs) -> Generation

POST/generations

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

ParametersExpandCollapse

prompt: str

Text prompt

maxLength: 6000

aspect_ratio: Optional[Literal["3:1", "2:1", "21:9", 10 more]]

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

One of the following:

"3:1"

"2:1"

"21:9"

"16:9"

"4:3"

"3:2"

"1:1"

"4:5"

"3:4"

"2:3"

"9:16"

"1:2"

"1:3"

image_ref: Optional[Iterable[ImageRefParam]]

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

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

layering: Optional[Layering]

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: Optional[Literal["1k", "2k"]]

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:

"1k"

"2k"

model: Optional[Model]

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"

output_format: Optional[Literal["png", "jpeg"]]

Output image format

One of the following:

"png"

"jpeg"

source: Optional[ImageRefParam]

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

style: Optional[Literal["auto", "manga"]]

Style preset (auto, manga)

One of the following:

"auto"

"manga"

type: Optional[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"

user_id: Optional[str]

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: Optional[VideoOptionsParam]

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

web_search: Optional[bool]

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

ReturnsExpandCollapse

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

Create a generation

HTTPTypeScriptPythonGoCLI Tool

import os
from luma_agents import Luma

client = Luma(
    auth_token=os.environ.get("LUMA_AGENTS_API_KEY"),  # This is the default and can be omitted
)
generation = client.generations.create(
    prompt="A glass of iced coffee on a marble countertop, morning light streaming through a window",
)
print(generation.id)

201 example

{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "created_at": "created_at",
  "model": "uni-1",
  "state": "queued",
  "type": "image",
  "failure_code": "content_moderated",
  "failure_reason": "failure_reason",
  "output": [
    {
      "type": "type",
      "url": "https://example.com",
      "layer": {
        "alpha_hint": "alpha_hint",
        "description": "description",
        "index": 0,
        "label": "label",
        "bounds": {
          "canvas_height": 0,
          "canvas_width": 0,
          "height": 0,
          "width": 0,
          "x": 0,
          "y": 0
        },
        "contains_text": true,
        "text": {
          "content": "content",
          "decorated": true,
          "font": {
            "category": "sans serif",
            "families": [
              "string"
            ],
            "italic": true,
            "weight": "thin",
            "width": "condensed",
            "match": {
              "face_id": "face_id",
              "family_id": "family_id",
              "family_name": "family_name",
              "style": "normal",
              "weight": 0
            }
          }
        }
      }
    }
  ],
  "usage": {
    "credits_charged": 0
  }
}

Returns Examples

201 example

{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "created_at": "created_at",
  "model": "uni-1",
  "state": "queued",
  "type": "image",
  "failure_code": "content_moderated",
  "failure_reason": "failure_reason",
  "output": [
    {
      "type": "type",
      "url": "https://example.com",
      "layer": {
        "alpha_hint": "alpha_hint",
        "description": "description",
        "index": 0,
        "label": "label",
        "bounds": {
          "canvas_height": 0,
          "canvas_width": 0,
          "height": 0,
          "width": 0,
          "x": 0,
          "y": 0
        },
        "contains_text": true,
        "text": {
          "content": "content",
          "decorated": true,
          "font": {
            "category": "sans serif",
            "families": [
              "string"
            ],
            "italic": true,
            "weight": "thin",
            "width": "condensed",
            "match": {
              "face_id": "face_id",
              "family_id": "family_id",
              "family_name": "family_name",
              "style": "normal",
              "weight": 0
            }
          }
        }
      }
    }
  ],
  "usage": {
    "credits_charged": 0
  }
}