Skip to content
Getting started

Quickstart

Generate and edit images and videos with the Luma Agents REST API — quickstart, SDKs, and authentication.

The Luma Agents API provides access to Luma’s image and video models — uni-1 and uni-1-max for images, Ray 3.2 for video — through a single async REST surface. Submit a generation request, poll for the result, and download your output.

The workflow is three steps:

  1. Submit a generation request via POST /v1/generations
  2. Poll for status via GET /v1/generations/{generation_id}
  3. Download images or videos from presigned URLs once the state reaches completed
import time
from luma_agents import Luma
client = Luma()
# 1. Submit
generation = client.generations.create(
prompt="A glass of iced coffee on a marble countertop, morning light streaming through a window",
aspect_ratio="16:9",
)
# 2. Poll
while generation.state not in ("completed", "failed"):
time.sleep(2)
generation = client.generations.get(generation.id)
# 3. Download
if generation.state == "completed":
print(f"Image URL: {generation.output[0].url}")
else:
print(f"Failed: {generation.failure_reason} (code: {generation.failure_code})")

Set model to "ray-3.2", type to "video", and pass output options under video. Polling and download work the same way.

generation = client.generations.create(
model="ray-3.2",
type="video",
prompt="A slow dolly shot through a misty greenhouse at sunrise",
aspect_ratio="16:9",
video={
"resolution": "720p",
"duration": "5s",
},
)

For image-to-video, pass an ImageRef as video.start_frame and/or video.end_frame. See Video generation for the full parameter set.

To edit an existing image instead, set type to "image_edit" and provide a source. Polling and download are identical to the generate flow above.

generation = client.generations.create(
type="image_edit",
prompt="Change the sky to a dramatic sunset with orange and purple clouds",
source={"url": "https://example.com/landscape.jpg"},
)

See Image editing for image_ref, style transfer, and base64 source images. To edit a video, set type to "video_edit" with a source video — source.generation_id, a hosted source.url, or inline source.data — see Video editing. To change a video’s aspect ratio, use type: "video_reframe" — see Video reframing.

A fixed 2-second interval is enough; you don’t need exponential backoff. Add two things: a hard deadline so a stalled job can’t hang your worker, and an initial wait before the first poll.

For video, use a longer initial wait and deadline: start with a 30-second initial wait and a 10-minute hard timeout. See Video generation — Polling for a video template.

If you record what each generation cost, usage.credits_charged can still be null after the generation reaches completed. To read it, keep polling the same generation with a growing interval and your own cutoff. See What one generation cost.

deadline = time.time() + 120 # 2-minute hard timeout
time.sleep(20)
while generation.state not in ("completed", "failed"):
if time.time() > deadline:
raise TimeoutError(f"Generation {generation.id} did not complete in time")
generation = client.generations.get(generation.id)
time.sleep(2)

Every request requires a Bearer token in the Authorization header. Set your API key as the LUMA_AGENTS_API_KEY environment variable — the official SDKs read it automatically.

Terminal window
export LUMA_AGENTS_API_KEY="luma-api-..."
https://agents.lumalabs.ai/v1
MethodPathDescription
POST/v1/generationsSubmit an image or video generation, edit, or reframe job
GET/v1/generations/{generation_id}Poll for generation status, output and credits charged

If you build on the Agents API on behalf of your own users, pass an optional user_id on POST /v1/generations — a stable, opaque identifier for the end user (no PII, max 256 characters):

{
"prompt": "A sunset over the ocean",
"user_id": "your-internal-user-id"
}

It’s forwarded to upstream model providers as their per-user tagging field, so trust & safety issues can be attributed to a specific end user rather than your whole account, and it powers per-end-user usage breakdowns. Strongly recommended for partner integrations.

Every generation response, from POST /v1/generations and GET /v1/generations/{generation_id}, returns the user_id the generation was created with, trimmed of surrounding whitespace, or null when none was sent or it was the Luma user id of the project’s creator.

Terminal window
pip install luma-agents

Every response includes X-Request-Id and X-API-Version headers. Successful generation requests also include rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). See Rate limits and headers for details.