---
title: "Create a generation"
method: POST
path: "/generations"
tags: ["Generations"]
---

# Create a generation

`POST /generations`

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

## Request body

- CreateGenerationRequest — Request body for submitting a generation
  - `model` '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.
  - `type` 'image' | 'image_edit' | 'video' | 'video_edit' | 'video_reframe' | 'layering' — The kind of generation to perform
  - `prompt` string, required — Text prompt
  - `user_id` string, nullable — 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.
  - `aspect_ratio` '3:1' | '2:1' | '21:9' | '16:9' | '4:3' | '3:2' | '1:1' | '3:4' | '2:3' | '9:16' | '1:2' | '1:3' — Output aspect ratio. Valid values depend on the selected model and generation type; the server validates the final model-specific set.
  - `style` 'auto' | 'manga' — Style preset for image generation
  - `output_format` 'png' | 'jpeg' — Output image format
  - `source` 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.
    - `url` string, nullable — Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.
    - `media_type` string, nullable — 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.
    - `data` string, nullable — Base64-encoded image or video data
    - `file_id` string, uuid, nullable — 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.
    - `generation_id` string, uuid, nullable — 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.
  - `image_ref` ImageRef[] — Reference images for style/content guidance. Up to 9 for type 'image', up to 8 for type 'image_edit'.
    - `url` string, nullable — Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.
    - `media_type` string, nullable — 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.
    - `data` string, nullable — Base64-encoded image or video data
    - `file_id` string, uuid, nullable — 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.
    - `generation_id` string, uuid, nullable — 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.
  - `web_search` boolean — Enable web search grounding — the agent can search the web and download reference images before generating.
  - `video` 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`.
    - `resolution` '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.
    - `duration` '5s' | '10s' — Video duration
    - `hdr` boolean, nullable — Generate HDR video. Requires HDR access. Not supported for video_reframe.
    - `exr_export` boolean, nullable — Export EXR alongside the MP4. Requires hdr=true.
    - `loop` boolean, nullable — Generate a seamlessly looping video. Only valid for type=video; not supported with duration=10s or hdr=true.
    - `start_frame` 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.
      - `url` string, nullable — Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.
      - `media_type` string, nullable — 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.
      - `data` string, nullable — Base64-encoded image or video data
      - `file_id` string, uuid, nullable — 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.
      - `generation_id` string, uuid, nullable — 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.
    - `end_frame` 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.
      - `url` string, nullable — Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.
      - `media_type` string, nullable — 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.
      - `data` string, nullable — Base64-encoded image or video data
      - `file_id` string, uuid, nullable — 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.
      - `generation_id` string, uuid, nullable — 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.
    - `keyframes` ImageRef[], nullable — 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.
      - `url` string, nullable — Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.
      - `media_type` string, nullable — 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.
      - `data` string, nullable — Base64-encoded image or video data
      - `file_id` string, uuid, nullable — 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.
      - `generation_id` string, uuid, nullable — 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.
    - `keyframe_indexes` integer[], nullable — 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.
    - `edit` 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.
      - `strength` 'adhere_1' | 'adhere_2' | 'adhere_3' | 'flex_1' | 'flex_2' | 'flex_3' | 'reimagine_1' | 'reimagine_2' | 'reimagine_3' — How much a video edit preserves or reimagines the source
      - `auto_controls` boolean, nullable — When true, the model derives the control schedule from the source video. When omitted, supplying strength or controls implies manual mode.
      - `controls` AdvancedControls — Per-signal manual conditioning controls for video edits
        - `pose` PoseControl — Pose / skeleton conditioning control
          - `enabled` boolean, nullable — Enable or disable pose conditioning. Omit to use the model default.
          - `strength` 'precise' | 'coarse' — Pose-conditioning strength
        - `depth` DepthControl — Depth / scene-geometry conditioning control
          - `enabled` boolean, nullable — Enable or disable depth conditioning. Omit to use the model default.
          - `blur` number, float, nullable — Depth-map blur amount from 0 to 1. Higher values allow more geometric freedom.
        - `normals` NormalsControl — Surface-normals conditioning control
          - `enabled` boolean, nullable — Enable or disable normals conditioning. Omit to use the model default.
          - `augmentation` number, float, nullable — Surface-normals augmentation from 0 to 1. Higher values allow more reinterpretation of surface geometry.
        - `trajectory` TrajectoryControl — Motion-trajectory conditioning control
          - `enabled` boolean, nullable — Enable or disable trajectory conditioning. Omit to use the model default.
          - `sparsity` number, float, nullable — Point-trajectory sparsity from 0 to 1. Higher values use fewer motion anchors.
        - `face` FaceControl — Face-identity conditioning control
          - `enabled` boolean, nullable — Enable or disable face conditioning. Omit to use the model default.
      - `keyframes` ImageRef[], nullable — 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[].
        - `url` string, nullable — Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.
        - `media_type` string, nullable — 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.
        - `data` string, nullable — Base64-encoded image or video data
        - `file_id` string, uuid, nullable — 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.
        - `generation_id` string, uuid, nullable — 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.
      - `keyframe_indexes` integer[], nullable — 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.
    - `source_position` SourcePosition — Normalized source rectangle inside the output canvas for video_reframe. Omit to let the model choose the default centered-fit crop.
      - `x_norm` number, float, required — Left edge of the source rectangle, as a fraction of canvas width. May be negative when the source extends off-canvas.
      - `y_norm` number, float, required — Top edge of the source rectangle, as a fraction of canvas height. May be negative when the source extends off-canvas.
      - `w_norm` number, float, required — Source rectangle width, as a fraction of canvas width. Up to 2.0 so the source can bleed off-canvas.
      - `h_norm` number, float, required — Source rectangle height, as a fraction of canvas height. Up to 2.0 so the source can bleed off-canvas.
  - `layering` LayeringOptions — 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` '1k' | '2k' — Output resolution for every extracted layer. 1k is faster and lower cost; 2k re-renders each layer at higher quality (priced higher, per layer).

## Response `201`

Generation submitted

- GenerationResponse — Generation status and output
  - `id` string, uuid, required — Generation identifier
  - `type` 'image' | 'image_edit' | 'video' | 'video_edit' | 'video_reframe' | 'layering', required — The kind of generation to perform
  - `state` 'queued' | 'processing' | 'completed' | 'failed', required — Current state of the generation
  - `model` 'uni-1' | 'uni-1-max' | 'ray-3.2', required — 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.
  - `created_at` string, required — Creation timestamp
  - `output` GenerationOutput[] — Generated outputs (populated on completion)
    - `type` string, required — Media type (e.g. image, video)
    - `url` string, uri, required — Presigned URL (1hr expiry)
    - `layer` GenerationOutputLayer — Per-layer semantics for a type=layering output
      - `index` integer, required — Layer position, front-to-back; the last layer is the background
      - `label` string, required — Short (1-2 word) layer name
      - `description` string, required — Complete-element caption for the layer's content
      - `alpha_hint` string, required — Edge treatment of the layer's transparency — soft (hair/fur/glass), hard (solid edges), or none (the opaque background)
  - `failure_reason` string, nullable — Human-readable failure description
  - `failure_code` 'content_moderated' | 'generation_failed' | 'budget_exhausted' | 'output_not_found' | 'image_too_large' | 'unsupported_format' | 'corrupt_input' | 'invalid_request' | 'rate_limited' — Machine-readable failure code for programmatic handling

## Other responses

- `400` — Validation error
- `401` — Missing or invalid API key
- `402` — Insufficient credits
- `403` — Model not available on plan
- `413` — Input media exceeds size limit
- `422` — Invalid media reference (bad base64 data or URL fetch failure)
- `429` — Rate or concurrent job limit exceeded
- `502` — Upstream service unavailable (fetch proxy or scope provisioning)
- `503` — Image URL ingestion unavailable (fetch proxy not configured)

---

[API](https://skmtc.net/lumalabs/apis/luma-agents-api.md) · [All operations](https://skmtc.net/lumalabs/apis/luma-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lumalabs/luma-agents-api/versions/2135bbde249c/schema)