Skip to content
Core concepts

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.

Terminal window
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"
}'

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 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.

Terminal window
curl -s "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/runs/$RUN_ID?wait_s=30" \
-H "Authorization: Bearer $SESSION_TOKEN"
{
"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.

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.

Terminal window
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" }
}
}'
You wantSend
Text to videotype: "video" with a prompt
Start or end on an imagevideo.start_frame, video.end_frame
Pin images through the clipvideo.keyframes with video.keyframe_indexes
Extend a clipvideo.start_frame (forward) or video.end_frame (backward) set to { "generation_id": "…" }
Restyle a cliptype: "video_edit" with a source
Change a clip’s shapetype: "video_reframe" with a source and the new aspect_ratio
A seamless loop, HDR, EXRvideo.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.

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:

FieldWhat it takes
durationClip length in seconds, as a number. Luma’s ray-3.2 uses video.duration instead.
mediasInputs, each a reference plus a role: reference, start_frame, end_frame, keyframe, reference_video or reference_audio.
parametersThe 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.

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.

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/generationsGenerate run
Modelsuni-1, uni-1-max, Ray 3.2uni-1, Ray 3.2 and the third-party image and video models the session allows. uni-1-max is not available
Output typesImage, video, layersImage, video, layers
Where results liveA URL that expiresThe session’s workspace, by asset_id, for later runs and briefs
InputsURLs, inline data, file_id, your earlier generation_idThe same, plus any workspace asset_id. generation_id only for generations already in the workspace
Execution modeSubmit, then pollStart a run, then wait on it or follow the stream. Runs alongside a brief on the same session. Same concurrency limit
CredentialsAPI keySession token
BillingCredits per generationCredits per generation. No agent reasoning is charged

Smaller differences:

  • web_search has no effect on a generate run.
  • Without aspect_ratio, a generate run uses 16:9; /v1/generations lets the model choose. Send aspect_ratio whenever the shape matters.
  • 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 with 429, 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", a source and a prompt up to 500 characters. It works like layering on the API.