Start Run
const url = 'https://agents.lumalabs.ai/v1/sessions/example/runs';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"aspect_ratio":"4:5","kind":"generate","model":"uni-1","prompt":"a white running shoe on an orange gradient, studio light","type":"image"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://agents.lumalabs.ai/v1/sessions/example/runs \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "aspect_ratio": "4:5", "kind": "generate", "model": "uni-1", "prompt": "a white running shoe on an orange gradient, studio light", "type": "image" }'Start a run on this session. 202 with the handle to await.
The body is discriminated on kind — brief, generate and
capability all answer with the same handle.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”Brief the session's agent, as a run.
content works for every session. input is the structured spelling
for an app-bound session whose app declares typed run intake.
object
Workspace assets to hand the agent: a prior run's output or an upload in this session's scope, by asset_id.
Ids of attachments already uploaded to this session.
Things of your team for the session's agent to follow on this message and the work it orders, each by the id its own list prints: brand_kit:
Brief the session's agent, as a run.
content works for every session. input is the structured spelling
for an app-bound session whose app declares typed run intake.
object
Workspace assets to hand the agent: a prior run's output or an upload in this session's scope, by asset_id.
Ids of attachments already uploaded to this session.
Things of your team for the session's agent to follow on this message and the work it orders, each by the id its own list prints: brand_kit:
object
One-shot generation as a run on this session.
The run dispatches one generation through the session, gated by the
session's model grant, with no agent turn. A third-party model also takes
duration, medias and parameters. The output lands in the
session's workspace, so a later run can name it by asset_id. It is
recorded in the session's history when it starts and when it ends, so a
later brief can refer to it. It may start while a brief, a capability or
another generate run is open on the session.
The session names the workspace this run writes to. A body field that tries to redirect the output elsewhere is dropped, not honoured — that is how an asset ends up somewhere the caller cannot list.
object
Things of your team this one output follows, each by the id its own list prints: brand_kit:
Reference images for style/content guidance. Up to 9 for type 'image', up to 8 for type 'image_edit' (source occupies one slot).
A MediaRef with the workspace arm — runs only.
A run writes into the session's workspace, so "an asset the workspace
already holds" means something there. /v1/generations has no session
and no workspace to resolve against, which is why this is a subclass and
not a sixth arm on MediaRef: the base class is what the published SDK
renders, and an arm no sessionless caller can use does not belong in it.
Layering options. Applies only to type=layering; rejected on every other type.
The image to split goes in source, and prompt may carry optional
guidance for how to split it (up to 500 characters, may be empty). Unknown
keys are rejected rather than ignored.
object
Output resolution for every layer. 2k re-renders each layer at higher quality and costs more; either is one flat price per generation, whatever the number of layers.
One media input to a third-party model: a ref, and the role that picks the model field it lands in.
object
What the media is to the model: reference (a reference image), start_frame, end_frame, keyframe (an image on the model's keyframe timeline, spaced evenly from the first frame to the last in the order sent), reference_video or reference_audio. A role the model does not take is refused, naming the roles it takes.
Model to use
Uni-1 output image format.
Text prompt
A MediaRef with the workspace arm — runs only.
A run writes into the session's workspace, so "an asset the workspace
already holds" means something there. /v1/generations has no session
and no workspace to resolve against, which is why this is a subclass and
not a sixth arm on MediaRef: the base class is what the published SDK
renders, and an arm no sessionless caller can use does not belong in it.
Style preset (auto, manga)
Generation type
VideoControls whose every frame slot carries the workspace arm.
object
VideoEditControls whose keyframes carry the workspace arm.
object
Per-signal manual conditioning overrides for a Ray 3.2 video edit.
Each signal is a self-describing sub-object — an enabled toggle plus
(for most signals) a single tuning value. Supplying controls puts the
edit into manual mode for the signals you specify; omit it entirely to let
the model auto-derive the full control schedule from the source video.
object
Face-identity conditioning (no extra tuning knob beyond enabled).
A MediaRef with the workspace arm — runs only.
A run writes into the session's workspace, so "an asset the workspace
already holds" means something there. /v1/generations has no session
and no workspace to resolve against, which is why this is a subclass and
not a sixth arm on MediaRef: the base class is what the published SDK
renders, and an arm no sessionless caller can use does not belong in it.
A MediaRef with the workspace arm — runs only.
A run writes into the session's workspace, so "an asset the workspace
already holds" means something there. /v1/generations has no session
and no workspace to resolve against, which is why this is a subclass and
not a sixth arm on MediaRef: the base class is what the published SDK
renders, and an arm no sessionless caller can use does not belong in it.
A MediaRef with the workspace arm — runs only.
A run writes into the session's workspace, so "an asset the workspace
already holds" means something there. /v1/generations has no session
and no workspace to resolve against, which is why this is a subclass and
not a sixth arm on MediaRef: the base class is what the published SDK
renders, and an arm no sessionless caller can use does not belong in it.
A MediaRef with the workspace arm — runs only.
A run writes into the session's workspace, so "an asset the workspace
already holds" means something there. /v1/generations has no session
and no workspace to resolve against, which is why this is a subclass and
not a sixth arm on MediaRef: the base class is what the published SDK
renders, and an arm no sessionless caller can use does not belong in it.
Normalized source rect inside the output canvas for video_reframe.
All fields are dimensionless ratios relative to the output canvas:
x_norm and y_norm are 0..1 (the source's top-left within
the canvas); w_norm and h_norm are 0..2.0 (the source can
extend past the canvas edges, in which case the AI outpaints the
visible portion only).
object
Source rect height, fraction of canvas height. Up to 2.0 (source can bleed off-canvas).
Source rect width, fraction of canvas width. Up to 2.0 (source can bleed off-canvas).
Left edge of source rect, fraction of canvas width. Negative when the source extends off-canvas to the left.
Top edge of source rect, fraction of canvas height. Negative when the source extends off-canvas to the top.
A MediaRef with the workspace arm — runs only.
A run writes into the session's workspace, so "an asset the workspace
already holds" means something there. /v1/generations has no session
and no workspace to resolve against, which is why this is a subclass and
not a sixth arm on MediaRef: the base class is what the published SDK
renders, and an arm no sessionless caller can use does not belong in it.
Enable web search grounding — the agent can search the web and download reference images before generating. Similar to Google Imagen's image search feature.
Run one of Luma's capabilities under this session, as a child of it.
The app runs in a session of its own that the caller never addresses: its
gates arrive on this session's feed carrying the run_id, its outputs
and summary land on this run, and its spend rolls up here. Takes no
attachment_ids — an attachment is authorized against the session it was
uploaded to, and the app's session is not the one the caller holds. A typed
input may name workspace assets in the app's declared fields; a
free-form content brief names them by asset_id.
Run one of Luma's capabilities under this session, as a child of it.
The app runs in a session of its own that the caller never addresses: its
gates arrive on this session's feed carrying the run_id, its outputs
and summary land on this run, and its spend rolls up here. Takes no
attachment_ids — an attachment is authorized against the session it was
uploaded to, and the app's session is not the one the caller holds. A typed
input may name workspace assets in the app's declared fields; a
free-form content brief names them by asset_id.
Responses
Section titled “ Responses ”Successful Response
One run as a caller reads it — the single handle and the single wait.
object
What kind of work a run performs. Mirrors db.ApiRunKind.
Assets this run produced.
One asset a run produced. The durable handle is asset_id.
object
One layer of a layering output.
object
Edge treatment of the layer's transparency — soft (hair/fur/glass), hard (solid edges), or none (the opaque background).
Placement of this layer's pixels within the composite canvas. Absent only when the output's dimensions could not be resolved.
object
Height of the full composite canvas the layers reassemble into.
Width of the full composite canvas the layers reassemble into.
Pixel height of the returned layer image.
Pixel width of the returned layer image.
Left offset of this layer's pixels within the composite canvas.
Top offset of this layer's pixels within the composite canvas.
Whether the layer was planned as typeset text (a headline, caption, or label) rather than an image element. Absent when not reported for this output.
Complete-element caption for the layer's content.
Layer position, front-to-back; the last layer is the background.
Short (1-2 word) layer name.
The text read off a contains_text layer, so it can be re-typeset as live text inside bounds. Absent when the layer holds no text, or its lettering could not be read or is a logo / wordmark. Final whenever the job is. A layering job is not reported finished until reading its text has finished or timed out.
object
The text as shown, preserving capitalization, with a line break between lines.
True when the lettering is ornamental (outlines, patterned fills, bevels, drop shadows), so plain typeset text will not reproduce its look.
Described typeface traits. Absent when they could not be read.
object
Letterform style.
Up to three Google Fonts family names that resemble the lettering, closest first. Empty when none of the offered families fit.
Whether the letters are slanted or cursive.
The font in your font catalog that the lettering matches, so you can re-set the text in it. Absent when no catalog font matches closely enough, or matching is not enabled. The image itself is not rendered in this font.
object
Typed ref of the matched face (one weight and style), font_face:
Typed ref of the matched font family, font_family:
Name of the matched font family.
Style of the matched face.
CSS font weight of the matched face, e.g. 400 or 700.
Stroke weight.
Letter width for its height.
True when this idempotency_key had already started a run: that run is echoed and no second one was started.
A run's lifecycle state. Mirrors db.ApiRunState.
Example
{ "kind": "brief", "outputs": [ { "layer": { "alpha_hint": "soft", "text": { "font": { "category": "sans serif", "match": { "style": "normal" }, "weight": "thin", "width": "condensed" } } } } ], "replayed": false, "state": "queued"}Validation Error
object
object
object
Examplegenerated
{ "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ]}