API FAQ: Uni-1, Uni-1-Max, Ray 3.2

Updated 21 Aug 2026 by Martin

*The article below is a general overview. For the most up to date information, please visit: https://docs.agents.lumalabs.ai

1. Getting Started & Models

What is the Luma Agents API?

The Luma Agents API is an asynchronous REST API for programmatic image and video generation. A single unified endpoint handles image generation, image editing, video generation/extension, video editing, and video reframing:

POST /v1/generations: Submits a job (returns immediately with 201 and state: "queued").
GET /v1/generations/{id}: Polls job status and retrieves output presigned download URLs upon completion.

What are the image models (`uni-1` vs `uni-1-max`)?

Both models share the exact same wire format, parameters (aspect_ratio, image_ref, source), and features (text rendering, style transfer, spatial reasoning, multi-panel layouts).

uni-1: The default, high-speed, cost-effective image generation and editing model.
uni-1-max: Produces superior output quality for hero images or ad creative where higher per-image cost is justified. Switch models by updating the "model" string.

What is Ray 3.2?

ray-3.2 is Luma's core video model on the Agents API. It supports:

Text-to-Video & Image-to-Video: type: "video" (supports video.start_frame and video.end_frame anchors).
Single-Keyframe Video Extension: Extends existing clips.
Video Editing: type: "video_edit".
Aspect Ratio Reframing: type: "video_reframe".

Is there a sandbox or staging environment?

No. There is no sandbox environment. Test workflows by making standard calls using test keys and smaller outputs.

2. Authentication & Keys

How do I authenticate API requests?

Pass your API key as a Bearer token in the Authorization header:

Bash


Authorization: Bearer luma-api-xxxxxxxxxxxx

Can I retrieve a lost key?

No. Raw keys (starting with luma-api-) are shown only once upon creation. The server stores a hash. If lost, revoke the key in the dashboard and generate a new one.

How do multiple keys work under one account?

You can create multiple named keys (e.g., production, staging). However, rate limits, concurrent job slots, and quotas are scoped at the client level, not the individual key level. All keys under the same client share concurrency and can poll each other's jobs.

3. Prompts & Style Controls

What are the prompt length boundaries?

Prompts must strictly be between 1 and 6,000 characters. Empty strings or prompts exceeding 6,000 characters are immediately rejected. Most production prompts perform best under 1,000 characters.

Does the API support negative prompts?

No. There is no negative_prompt parameter. Construct prompts positively (e.g., "a calm, empty street at dawn" instead of "a street with no people or cars").

How do I render readable text inside images?

Enclose literal text strings in double quotes directly inside the prompt:

"A wooden coffee shop sign with the text 'Aroma Cafe' painted in white sans-serif font."

Shorter text strings (under 20 characters) render with the highest fidelity.

Can I seed prompts for deterministic outputs?

No. Every request uses a random internal seed, and there is no public seed parameter. To maintain visual consistency across multiple calls, supply image style anchors via image_ref.

How does `style: "manga"` work?

Setting style: "manga" enforces a comic-page aesthetic with ink outlines and screentone shading.

Constraint: style: "manga" requires a portrait aspect ratio (2:3, 9:16, 1:2, or 1:3). Passing landscape or square aspect ratios on type: "image" returns a 422 error.
Exception: On type: "image_edit", style: "manga" works regardless of aspect ratio because output dimensions inherit directly from the source image.

4. Aspect Ratios & Output Specifications

Which aspect ratios are supported?

Supported ratios vary strictly by model and request type:

Model / Type	Supported Aspect Ratios	Note
`uni-1` / `uni-1-max` (`type: "image"`)	`3:1`, `2:1`, `16:9`, `3:2`, `1:1`, `2:3`, `9:16`, `1:2`, `1:3`	9 ratios total
`ray-3.2` (`type: "video"`)	`9:16`, `3:4`, `1:1`, `4:3`, `16:9`, `21:9`	6 ratios total
Image / Video Edits (`type: "image_edit"`, `type: "video_edit"`)	Derived from source	Explicit `aspect_ratio` input is ignored
Video Reframe (`type: "video_reframe"`)	`9:16`, `3:4`, `1:1`, `4:3`, `16:9`, `21:9`	Required parameter

How are output resolutions and formats set?

Images (type: "image"): Resolution is automatically computed from the aspect ratio. Supported formats are pngand jpeg.
Image Edits (type: "image_edit"): Preserves the exact width and height of the source image.
Video (ray-3.2): Explicitly set via video.resolution (540p, 720p, or 1080p).

How long do output presigned URLs remain valid?

Presigned download URLs expire after 1 hour. Every time you poll GET /v1/generations/{id}, a fresh URL with a new 1-hour window is minted. Download files directly to your own storage infrastructure rather than serving presigned URLs directly to end users.

5. Image Editing & Reference Images

What is the difference between `source` and `image_ref`?

source: The primary base image being transformed in type: "image_edit". It preserves output dimensions and consumes 1 slot in the reference pipeline.
image_ref: An optional array of reference images used for style, color, character, or composition guidance on both type: "image" and type: "image_edit".

What are the payload and dimension limits for input images?

Max Reference Images: Up to 9 for type: "image"; up to 8 for type: "image_edit" (since source takes the 9th slot).
Max Byte Size: 50 MB per image (decoded base64 or URL stream). Production best practice is keeping images under 4 MB at JPEG quality 85–92.
Max Dimensions: Neither side may exceed 8,000 px.

How must URLs be configured for image ingestion?

Image URLs are retrieved server-side via a strict proxy. Requirements include:

Must use https:// (HTTP is rejected).
Must resolve to a public IP (RFC1918, loopback, internal VPN hostnames, and local network IPs are blocked).
Must return a valid image/* MIME content-type within 18 seconds.

6. Video Editing & Reframing (`ray-3.2`)

How do I supply a source video for edits or reframing?

For type: "video_edit" and type: "video_reframe", supply a single source video via one of three fields:

source.generation_id: The id of a prior completed video job owned by your client.
source.url: A public HTTPS video URL with source.media_type explicitly set (e.g., "video/mp4").
source.data: Inline base64-encoded video data with an explicit source.media_type.

What are the source video restrictions?

Max Duration: Must be 30 seconds or shorter.
Max File Size: Must be 200 MB or smaller.

What is the difference between `video_edit` and `video_reframe`?

video_edit: Restyles visual content, lighting, or subjects while preserving underlying motion. Output preserves the source video's aspect ratio.
video_reframe: Preserves original footage frame-for-frame while outpainting new imagery to fit a newly specified target aspect_ratio.

How do `video.edit` controls work?

Auto Mode (auto_controls: true): The model automatically calculates optimal conditioning schedules (Recommended default).
Manual Strength (video.edit.strength): Preset bands including adhere_1–adhere_3 (subtle changes), flex_1–flex_3(balanced), and reimagine_1–reimagine_3 (high prompt deviation).
Fine-Grained Controls (video.edit.controls): Toggles individual signal weights (pose, depth, normals, trajectory, face). Note: Manual controls cannot be combined with auto_controls: true.

7. Polling, Rate Limits & Errors

What are the API states?

Jobs progress through four states: queued $\rightarrow$ processing $\rightarrow$ completed or failed.

What is the recommended polling strategy?

Interval: Poll GET /v1/generations/{id} every 2 to 3 seconds.
Timeouts: Image jobs take 30–60 seconds; set a hard client polling timeout around 2 minutes.

How do rate limits work?

Rate limits operate across two distinct metrics per client account:

Requests Per Minute (RPM): Calculated via a 60-second sliding window.
Concurrent-Job Slots: The maximum number of generations running simultaneously in queued or processing states. Submissions exceeding this ceiling return HTTP 429 with Retry-After: 60.

Common Failure Codes (Async Errors)


queued / processing  --->  failed (with failure_code)

failure_code	Cause	Action
`content_moderated`	Input or output flagged by safety filters	Do not retry verbatim. Modify prompt or input assets.
`download_failed`	Server could not fetch `source.url` or `image_ref`URL	Check URL accessibility, SSL, or switch to base64.
`unprocessable_image`	Image corrupted, invalid format, or dimensions $>8000\text{ px}$	Verify image integrity and dimensions.
`budget_exhausted`	Client account ran out of credits mid-generation	Add funds to account and resubmit job.
`internal_error`	Unexpected system pipeline fault	Retry request with exponential backoff.

8. Billing & Support

How does API billing work?

Pay-as-you-go: Billed per generation. Image costs depend on model (uni-1 vs uni-1-max), action type, and reference count. Video costs depend on duration (5s vs 10s), resolution, and dynamic range (hdr, exr_export).
Failed Generations: Synchronous errors and system faults (internal_error) are not charged. Input errors or moderation blocks (content_moderated, download_failed, unprocessable_image) are charged as compute was consumed up to the failure point.

What information is required for support requests?

If you encounter unexpected issues, email support+luma-agents-api@lumalabs.ai and include:

Generation ID: The root id returned from POST /v1/generations.
Request ID: The X-Request-Id header value returned in the HTTP response headers.