Skip to content
Core concepts

Workflow apps

Offer a proven creative job, such as product shots or ads in every size, as a feature of your product, with consistent quality on every run.

A brief leaves the agent to decide how to do the work, which suits open-ended requests. For jobs that repeat, such as product-page shots for each new item or one ad in every size and language, Luma’s creative team builds workflow apps. Each one is a tested set of models, prompts and steps: you send the inputs and get finished images back, without building or tuning anything yourself.

These are the same apps your team finds under Solutions in the Luma app. The API lets you build them into your own product.

A few of the most used apps. They are the same pre-set workflows the Luma MCP runs in Claude and ChatGPT.

  1. In your session. Name the app on a message in the session you already have. Best for one result.
  2. Through the agent. Send an ordinary message. The agent starts an app when one fits the request.
  3. In an app session. Open a session that runs one app and nothing else, with no general-purpose agent in between.

Add capability to a user.message. This example turns one product photo into three product shots with Product Shots. You need $SESSION_TOKEN, $WORKSPACE_ID and $SESSION_ID from the Quickstart.

GET /v1/apps lists the apps your team can run. GET /v1/apps/{slug}/surface-template returns an app’s form as a JSON Schema in input_schema, and the release that schema belongs to in app_version.

Terminal window
curl -s https://agents.lumalabs.ai/v1/apps \
-H "Authorization: Bearer $SESSION_TOKEN" | jq -r '.[].slug'
curl -s https://agents.lumalabs.ai/v1/apps/product_shots/surface-template \
-H "Authorization: Bearer $SESSION_TOKEN" | jq '{app_version, input_schema}'

The form is one object, brief. For product_shots it takes:

FieldWhat it takes
product_image_idRequired. A list holding one asset id: the product photo.
background_modeRequired. auto, use_image or describe.
background_image_idsWith use_image: a list holding one asset id.
background_descriptionWith describe: the scene.
directionWith use_image: optional extra direction.
aspect_ratioauto, 1:1, 4:5, 3:4, 2:3, 9:16, 3:2, 4:3 or 16:9.
variant_count"1" to "6". Defaults to "3".
resolution"1K" or "2K".

Read the schema rather than hard-coding this table. It changes when the app does.

An app reads files from the workspace by asset id. A file you upload to the session lands in the workspace, and its attachment_id is its asset id. Wait until it is ready before you name it.

Terminal window
PRODUCT=$(curl -s -X POST \
"https://agents.lumalabs.ai/v1/attachments?session_id=$SESSION_ID" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-F "file=@bottle.png" | jq -r .attachment_id)
until [ "$(curl -s https://agents.lumalabs.ai/v1/attachments/$PRODUCT \
-H "Authorization: Bearer $SESSION_TOKEN" | jq -r .state)" != "pipeline_running" ]; do
sleep 2
done

A rejected state means the file can’t be used; rejection_reason says why. An asset the workspace already holds, such as an earlier output, works the same way.

Send a user.message with a capability part. app is the slug, and input is the form, filled in:

Terminal window
RUN_ID=$(curl -s -X POST https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "events": [ {
"type": "user.message",
"content": "Product shots of our bottle on a kitchen counter.",
"capability": {
"app": "product_shots",
"input": { "brief": {
"product_image_id": ["'"$PRODUCT"'"],
"background_mode": "describe",
"background_description": "a sunlit marble kitchen counter with lemons",
"variant_count": "3",
"resolution": "1K"
} }
},
"idempotency_key": "'"$SESSION_ID"'-shots-1"
} ] }' \
| jq -r '.data[0].result.run_id')

result.run_id in the response is the app’s run. Keep it: every event the app produces carries it.

  • The app starts straight away. The session’s agent doesn’t decide whether to run it.
  • content is still required. With input, the app reads it as your user’s own words beside the form.
  • Without input, content is the brief, and the message’s asset_ids name its files. With input, name files only inside the form; asset_ids next to input is refused.
  • A capability message takes asset_ids, never attachment_ids.
  • Retrying with the same idempotency_key returns the same run and starts nothing new.
  • system_context inside capability adds standing instructions for the app’s own work.
  • A form that doesn’t match the app’s schema is refused with RUN.INVALID_INPUT. See Errors.

The app’s work arrives on the session’s stream, mixed with everything else. Follow it by its run_id:

Terminal window
curl -s -N "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events/stream?after_seq=0" \
-H "Authorization: Bearer $SESSION_TOKEN"
EventMeans
run.startedThe app’s run began. It carries kind: "capability", app and the run_id.
agent.messageThe app talking. producer.kind is app, and producer.app names it.
job.started, job.completedA generation the app started is running, or has landed.
agent.gateThe app wants a decision before it continues. See below.
run.completedThe app finished. state is completed, failed or cancelled, with outputs and summary.

INPUT

bottle.png

uploaded, then named by id

ON THE WIRE

“capability”: {

“app”: “product_shots”,

“input”: { “brief”: {

“product_image_id”: [”…”],

“background_mode”: “describe”,

“background_description”:

“a sunlit marble kitchen

counter with lemons”,

“variant_count”: “3”,

“resolution”: “1K”

} } }

on a user.message

to POST /v1/sessions/{id}/events

OUTPUT run.completed → outputs[]

3 images, 1K

each with a url and an asset_id

What step 3 sends and what step 5 returns. The images are illustrations.

Review gates. If the app has a review step, it pauses and asks:

{
"type": "agent.gate",
"run_id": "4265445c-…",
"interaction": { "kind": "review", "invocation_id": "toolu_02…" }
}

Answer on the same /events route:

{
"type": "user.gate_verdict",
"invocation_id": "toolu_02…",
"verdict": { "verdict": "proceed" }
}

The shape of verdict belongs to the app. See Approvals and review.

The agent follows along. The run belongs to the session’s agent. When it ends, the agent tells your user about the result in an agent.message. The session stays open for more messages while the app works.

To stop the app, send a user.interrupt with its target_run_id. Without one, the interrupt stops all work on the session, apps included.

Read the run. wait_s holds the request open, up to 30 seconds, until the run settles:

Terminal window
curl -s "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/runs/$RUN_ID?wait_s=30" \
-H "Authorization: Bearer $SESSION_TOKEN" | jq '{state, summary, outputs}'

state is needs_input while a gate waits, and completed, failed or cancelled at the end. Each item in outputs has an asset_id, type, mime and a presigned url. The URL expires; read the run again for a fresh one, and keep the asset_id to use the shot in a later message or run.

You don’t have to name the app. Send an ordinary user.message, and when the request fits an app, the session’s agent starts it. It finds and runs apps with three tools:

ToolWhat the agent does with it
list_appsLists each app’s slug, name and description.
start_appStarts an app with a slug and a written brief. It runs like a capability run, and its result comes back to the agent.
answer_gateAnswers the app’s question for your user, only after your user has sent a message since the question was shown.

The agent holds these tools whenever your API key can run workflow apps. You follow its runs on the stream and answer review gates exactly as in step 4.

An app session runs one app and nothing else. There is no general-purpose agent in it: the app’s review gates come straight to you, its working document is on the session, and the session keeps one release from start to finish. Use it when a screen in your product is dedicated to one app.

Name the app when you create the session:

Terminal window
APP_SESSION_ID=$(curl -s -X POST https://agents.lumalabs.ai/v1/sessions \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "scope_id": "'"$WORKSPACE_ID"'", "app": "product_shots" }' \
| jq -r .session_id)

Start it the same way as in step 3: a user.message with capability. The differences from running an app in your own session:

  • The session’s release is fixed when you create it. The create response’s app names it as slug, version and package_digest, and a session keeps that release until it ends. slug@version on create works as a pin.
  • The app’s working document is on plan_artifact of GET /v1/sessions/{session_id}.
  • platform_tools, agents and skills are refused beside app. Your own client tools are allowed.

The app spends this session’s credits, and GET /v1/sessions/{session_id}/usage already includes it. The session’s cost_policy caps it with everything else the session does, so a session opened with "cost_policy": { "max_total_credits": 2000 } stops the app there too. See Budgets and usage.

Luma ships app improvements as new releases, and a run gets the active one. To fail fast if it changed since you tested, send app as slug@MAJOR.MINOR.PATCH, using the app_version your form came from. A pin is a check: a different active release is refused with APP.VERSION_NOT_ACTIVE, whose active_version names it.