Generations

Create a generation

Changed on

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

post/generations

Request

  • Base URL: https://agents.lumalabs.ai/v1
  • URL: https://agents.lumalabs.ai/v1/generations
  • Auth: HTTP bearer

Request body

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

promptstring required

Text prompt

user_idstring 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

web_searchboolean

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

Example request

{
  "prompt": "A glass of iced coffee on a marble countertop, morning light streaming through a window"
}

Response

Generation submitted

idstring 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_atstring required

Creation timestamp

failure_reasonstring 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

Changes

  • 2135bbde249cRevision changes
    • warning

      added the new layering enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the new layering enum value to the request property

    • info

      added the optional property // to the response with the status

  • 83f890190435Revision changes
    • info

      the request property's minLength was decreased from 1 to 0