Skip to content
Luma Agents
lumalabs.ai
API Reference
Generations

Create a generation

$ luma-agents-cli generations create
POST/generations

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

ParametersExpand Collapse
--prompt: string

Text prompt

--aspect-ratio: optional "3:1" or "2:1" or "16:9" or 6 more

Output aspect ratio

--image-ref: optional array of object { data, media_type, url }

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

--model: optional "uni-1" or "uni-1-max"

Model identifier. uni-1 is the default tier; uni-1-max produces higher-quality output than uni-1 at a higher per-image price. Both models are available to all accounts — see Pricing for per-image rates.

--output-format: optional "png" or "jpeg"

Output image format

--source: optional object { data, media_type, url }

Reference image for guided generation. Provide either url or inline base64 data (not both).

--style: optional "auto" or "manga"

Style preset (auto, manga)

--type: optional "image" or "image_edit"

The kind of generation to perform

--user-id: optional string

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.

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"

Model used

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

Current state of the generation

"queued"
"processing"
"completed"
"failed"
type: "image" or "image_edit"

The kind of generation to perform

"image"
"image_edit"
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 }

Generated outputs (populated on completion)

type: string

Media type (e.g. image)

url: string

Presigned URL (1hr expiry)

Create a generation

luma-agents-cli generations create \
  --auth-token 'My Auth Token' \
  --prompt 'A glass of iced coffee on a marble countertop, morning light streaming through a window'
{
  "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"
    }
  ]
}
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"
    }
  ]
}