--- title: Generate runs | Luma Agents description: 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`](/guides/index.md), and its output lands in the session’s workspace, where the agent or a later run can use it. ## Start a run - [cURL](#tab-panel-0-0) - [Python](#tab-panel-0-1) - [TypeScript](#tab-panel-0-2) ```bash 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" }' ``` ```python import json import 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"] ``` ```typescript const BASE = "https://agents.lumalabs.ai/v1"; async function post( path: string, body: unknown, token: string, headers: Record = {}, ) { 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](/agents/budgets/index.md). ## 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](/agents/streaming/index.md) for the run’s `run.completed`. - [cURL](#tab-panel-1-0) - [Python](#tab-panel-1-1) - [TypeScript](#tab-panel-1-2) ```bash curl -s "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/runs/$RUN_ID?wait_s=30" \ -H "Authorization: Bearer $SESSION_TOKEN" ``` ```python 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"]) ``` ```typescript 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); ``` ```json { "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 Everything on [Image generation](/guides/images/generation/index.md) 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. ```json { "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 Video uses `ray-3.2` and the same `video` object as [Video generation](/guides/videos/generation/index.md): `resolution`, `duration`, `loop`, `hdr`, `exr_export`, `start_frame`, `end_frame`, and `keyframes` with `keyframe_indexes`. - [cURL](#tab-panel-2-0) - [Python](#tab-panel-2-1) - [TypeScript](#tab-panel-2-2) ```bash 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" } } }' ``` ```python 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"}, ) ``` ```typescript 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](/guides/videos/generation/index.md). ## Third-party models A session can reach more models than the API. Their ids are in `GET /v1/models` (see [Models](/guides/model/index.md)). 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. | ```json { "kind": "generate", "type": "video", "model": "", "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 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 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](/agents/index.md). | | `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_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. ## 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 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](/guides/images/layering/index.md). ## Next - [Budgets and usage](/agents/budgets/index.md): what a run costs and how to cap it. - [Video generation](/guides/videos/generation/index.md): every video field and rule. - [Streaming](/agents/streaming/index.md): follow runs on the event stream.