Skip to content
Luma Agents
lumalabs.ai
API Reference
Generations

Get a generation

$ luma-agents-cli generations get
GET/generations/{generation_id}

Poll for generation status and output. On completion, the response includes presigned URLs to download the generated images.

ParametersExpand Collapse
--generation-id: string

Generation UUID returned by POST /generations

ReturnsExpand Collapse
generation: object { id, created_at, model, 5 more }

Generation status and output

id: string

Generation identifier

created_at: string

Creation timestamp

model: "uni-1" or "uni-1-max" or "ray-3.2"

Model used

"uni-1"
"uni-1-max"
"ray-3.2"
state: "queued" or "processing" or "completed" or "failed"

Current state of the generation

"queued"
"processing"
"completed"
"failed"
type: "image" or "image_edit" or "video" or 3 more

The kind of generation to perform

"image"
"image_edit"
"video"
"video_edit"
"video_reframe"
"layering"
failure_code: optional "content_moderated" or "generation_failed" or "budget_exhausted" or 6 more

Machine-readable failure code for programmatic handling

"content_moderated"
"generation_failed"
"budget_exhausted"
"output_not_found"
"image_too_large"
"unsupported_format"
"corrupt_input"
"invalid_request"
"rate_limited"
failure_reason: optional string

Human-readable failure description

output: optional array of GenerationOutput { type, url, layer }

Generated outputs (populated on completion)

type: string

Media type (e.g. image, video)

url: string

Presigned URL (1hr expiry)

layer: optional object { alpha_hint, description, index, 2 more }

Per-layer semantics for a type=layering output

alpha_hint: 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: number

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

label: string

Short (1-2 word) layer name

bounds: optional object { canvas_height, canvas_width, height, 3 more }

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: number

Height of the full composite canvas the layers reassemble into

canvas_width: number

Width of the full composite canvas the layers reassemble into

height: number

Pixel height of the returned layer image

width: number

Pixel width of the returned layer image

x: number

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

y: number

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

Get a generation

luma-agents-cli generations get \
  --auth-token 'My Auth Token' \
  --generation-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e
{
  "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
        }
      }
    }
  ]
}
Returns Examples
{
  "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
        }
      }
    }
  ]
}