Generate runs
Start one image generation on a session with no agent turn. Wait on the run, read its output, and choose its shape.
When you know exactly what you want, you don’t need the agent to plan it. A generate run sends one image or video generation straight to a model inside a session, with no agent turn. It takes the same body as POST /v1/generations, and its output lands in the session’s workspace, where the agent or a later run can use it.
Start a run
Section titled “Start a run”curl -s -X POST "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/runs" \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: shoe-hero-1" \ -d '{ "kind": "generate", "type": "image", "model": "uni-1", "prompt": "a white running shoe on an orange gradient, studio light", "aspect_ratio": "4:5" }'import jsonimport urllib.request
BASE = "https://agents.lumalabs.ai/v1"
def post(path, body, token, headers=None): request = urllib.request.Request( BASE + path, method="POST", data=json.dumps(body).encode(), headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", **(headers or {})}, ) with urllib.request.urlopen(request) as response: return json.load(response)
def get(path, token): request = urllib.request.Request(BASE + path, headers={"Authorization": f"Bearer {token}"}) with urllib.request.urlopen(request) as response: return json.load(response)
run = post( f"/sessions/{session_id}/runs", { "kind": "generate", "type": "image", "model": "uni-1", "prompt": "a white running shoe on an orange gradient, studio light", "aspect_ratio": "4:5", }, session_token, headers={"Idempotency-Key": "shoe-hero-1"},)run_id = run["run_id"]const BASE = "https://agents.lumalabs.ai/v1";
async function post( path: string, body: unknown, token: string, headers: Record<string, string> = {},) { const response = await fetch(BASE + path, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...headers, }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); return response.json();}
async function get(path: string, token: string) { const response = await fetch(BASE + path, { headers: { Authorization: `Bearer ${token}` }, }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); return response.json();}
const { run_id: runId } = await post( `/sessions/${sessionId}/runs`, { kind: "generate", type: "image", model: "uni-1", prompt: "a white running shoe on an orange gradient, studio light", aspect_ratio: "4:5", }, sessionToken, { "Idempotency-Key": "shoe-hero-1" },);The answer is 202 with the run, already running. Keep its run_id.
The model must be one the session is allowed to use. The run spends the session’s credits like any other generation, so it counts against the session’s budget.
Wait for the output
Section titled “Wait for the output”Wait on the run until state is completed or failed. Repeat the call if it returns while still running, or watch the stream for the run’s run.completed.
curl -s "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/runs/$RUN_ID?wait_s=30" \ -H "Authorization: Bearer $SESSION_TOKEN"run = get(f"/sessions/{session_id}/runs/{run_id}?wait_s=30", session_token)while run["state"] not in ("completed", "failed", "cancelled"): run = get(f"/sessions/{session_id}/runs/{run_id}?wait_s=30", session_token)for output in run.get("outputs", []): print(output["asset_id"], output["url"])let run = await get( `/sessions/${sessionId}/runs/${runId}?wait_s=30`, sessionToken,);while (!["completed", "failed", "cancelled"].includes(run.state)) { run = await get( `/sessions/${sessionId}/runs/${runId}?wait_s=30`, sessionToken, );}for (const output of run.outputs ?? []) console.log(output.asset_id, output.url);{ "run_id": "c23c99ad-ce81-444b-b1f2-8a95f1bb5d71", "kind": "generate", "state": "completed", "outputs": [ { "type": "image", "mime": "image/png", "asset_id": "9iPzzn2g", "url": "https://…" } ]}Store the asset_id, not the url. The URL expires after one hour, and GET /v1/sessions/$SESSION_ID/jobs returns the same output with a fresh one. To use the result in a later run or message, pass its asset_id.
Images
Section titled “Images”Everything on Image generation works here: type: "image" with image_ref references and a style, or type: "image_edit" with a source to change an existing picture. Anywhere the API takes an image (source, image_ref, video frames), a run also takes { "asset_id": "…" } for anything already in the workspace.
{ "kind": "generate", "type": "image_edit", "model": "uni-1", "prompt": "change the background to a beach at sunset", "source": { "asset_id": "9iPzzn2g" }}There is no width and height. Pick the shape with aspect_ratio; each model supports its own set, listed under capabilities.aspect_ratios in GET /v1/models. For an exact pixel size, generate at the nearest ratio and crop.
Video uses ray-3.2 and the same video object as Video generation: resolution, duration, loop, hdr, exr_export, start_frame, end_frame, and keyframes with keyframe_indexes.
curl -s -X POST "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/runs" \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: shoe-hero-video-1" \ -d '{ "kind": "generate", "type": "video", "model": "ray-3.2", "prompt": "the shoe slowly rotates as the light sweeps across it", "aspect_ratio": "16:9", "video": { "resolution": "720p", "duration": "5s", "start_frame": { "asset_id": "9iPzzn2g" } } }'video_run = post( f"/sessions/{session_id}/runs", { "kind": "generate", "type": "video", "model": "ray-3.2", "prompt": "the shoe slowly rotates as the light sweeps across it", "aspect_ratio": "16:9", "video": { "resolution": "720p", "duration": "5s", "start_frame": {"asset_id": "9iPzzn2g"}, }, }, session_token, headers={"Idempotency-Key": "shoe-hero-video-1"},)const videoRun = await post( `/sessions/${sessionId}/runs`, { kind: "generate", type: "video", model: "ray-3.2", prompt: "the shoe slowly rotates as the light sweeps across it", aspect_ratio: "16:9", video: { resolution: "720p", duration: "5s", start_frame: { asset_id: "9iPzzn2g" }, }, }, sessionToken, { "Idempotency-Key": "shoe-hero-video-1" },);| You want | Send |
|---|---|
| Text to video | type: "video" with a prompt |
| Start or end on an image | video.start_frame, video.end_frame |
| Pin images through the clip | video.keyframes with video.keyframe_indexes |
| Extend a clip | video.start_frame (forward) or video.end_frame (backward) set to { "generation_id": "…" } |
| Restyle a clip | type: "video_edit" with a source |
| Change a clip’s shape | type: "video_reframe" with a source and the new aspect_ratio |
| A seamless loop, HDR, EXR | video.loop, video.hdr, video.exr_export |
The rules that tie these together, such as 10s not working with start_frame or hdr, are the API’s. See Video generation.
Third-party models
Section titled “Third-party models”A session can reach more models than the API. Their ids are in GET /v1/models (see Models). A third-party model takes three fields that only exist on runs:
| Field | What it takes |
|---|---|
duration | Clip length in seconds, as a number. Luma’s ray-3.2 uses video.duration instead. |
medias | Inputs, each a reference plus a role: reference, start_frame, end_frame, keyframe, reference_video or reference_audio. |
parameters | The model’s own settings, keyed by its field names. |
{ "kind": "generate", "type": "video", "model": "<id from GET /v1/models>", "prompt": "a paper boat drifting down a rain-soaked street", "aspect_ratio": "9:16", "duration": 6, "medias": [{ "asset_id": "9iPzzn2g", "role": "start_frame" }], "parameters": { "resolution": "1080p" }}A role or a parameter value the model doesn’t take is refused, and the message names what it accepts. GET /v1/models/{id} lists a model’s options. aspect_ratio and duration stay top-level fields for every model, never inside parameters.
One at a time
Section titled “One at a time”A session runs one generate run at a time. Starting another while one is in flight is refused with 409 RUN.SESSION_BUSY, and the error’s run_id names the run to wait for. To make several at once, use a session for each. To have the agent plan and make a set, send a brief as a user.message instead.
How it differs from the Luma API
Section titled “How it differs from the Luma API”A generate run does what POST /v1/generations does, on a session. There is no agent turn, but the run is recorded on the session’s log and its output stays in the workspace. For the full comparison, see Agents API and the Luma API.
POST /v1/generations | Generate run | |
|---|---|---|
| Models | uni-1, uni-1-max, Ray 3.2 | uni-1, Ray 3.2 and the third-party image and video models the session allows. uni-1-max is not available |
| Output types | Image, video, layers | Image, video, layers |
| Where results live | A URL that expires | The session’s workspace, by asset_id, for later runs and briefs |
| Inputs | URLs, inline data, file_id, your earlier generation_id | The same, plus any workspace asset_id. generation_id only for generations already in the workspace |
| Execution mode | Submit, then poll | Start a run, then wait on it or follow the stream. Runs alongside a brief on the same session. Same concurrency limit |
| Credentials | API key | Session token |
| Billing | Credits per generation | Credits per generation. No agent reasoning is charged |
Smaller differences:
web_searchhas no effect on a generate run.- Without
aspect_ratio, a generate run uses16:9;/v1/generationslets the model choose. Sendaspect_ratiowhenever the shape matters.
Details
Section titled “Details”- A ratio the model doesn’t support is refused with
400 RUN.INVALID_INPUT, and the message lists the ratios it accepts. - A generate run you start can count against the same concurrent-job limit as
POST /v1/generations, from when it starts until its generation ends. When that limit is full the run is refused with429, no run is created, and you can retry with the same idempotency key. - Layering a workspace image into transparent layers is a run with
type: "layering", asourceand apromptup to 500 characters. It works like layering on the API.
- Budgets and usage: what a run costs and how to cap it.
- Video generation: every video field and rule.
- Streaming: follow runs on the event stream.