Skip to content
Getting started

Quickstart

Mint a session token, create a workspace and a session, send the agent a brief and watch it work, in five calls.

This takes you from an API key to a finished image from the agent. Each step keeps the id the next one needs, so run the steps in order in one terminal or one script. You need an API key in LUMA_AGENTS_API_KEY; the cURL tab also needs jq.

Your API key stays on your server. Use it to mint a short-lived token for one of your end users, and use that token for every later call.

Terminal window
SESSION_TOKEN=$(curl -s -X POST https://agents.lumalabs.ai/v1/auth/token \
-H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "user_id": "user-8812", "tenant_id": "customer-4417" }' \
| jq -r .session_token)

user_id is your id for the person. tenant_id is your id for their company, and it hides one customer’s work from every other customer.

Terminal window
WORKSPACE_ID=$(curl -s -X POST https://agents.lumalabs.ai/v1/scopes \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"key": "brand-workspace",
"display_name": "Example Bakery"
}' \
| jq -r .scope_id)

A workspace holds the assets your sessions make and use. Posting the same key again returns the same workspace.

Terminal window
SESSION_ID=$(curl -s -X POST https://agents.lumalabs.ai/v1/sessions \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-1" \
-d '{
"scope_id": "'"$WORKSPACE_ID"'",
"system_context": "You are the creative department for a small bakery.",
"expires_in_seconds": 3600,
"cost_policy": { "max_total_credits": 2000 }
}' \
| jq -r .session_id)

system_context is standing instructions the agent follows on every turn. max_total_credits caps what this session can spend.

Terminal window
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": "Make a square image of our sourdough loaf on a rustic table, morning light.",
"idempotency_key": "'"$SESSION_ID"'-msg-1"
} ] }'

The response has one entry per event you sent. "status": "accepted" in data[0] means the brief was recorded and the agent’s turn was scheduled; the work itself appears on the stream.

{
"data": [
{
"type": "user.message",
"status": "accepted",
"id": "sevt_emsbs",
"seq": 1,
"result": {
"run_id": "e2089f1e-5333-4eb1-985e-6ca88f3adb04",
"message_seq": 0
}
}
]
}
Terminal window
curl -s -N "https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events/stream?after_seq=0" \
-H "Authorization: Bearer $SESSION_TOKEN"

after_seq=0 replays the log from the start and then stays open, so it doesn’t matter that you sent the brief first. This is the log the brief above produced on production:

  1. 1Your briefuser.messageseq 1. Your input comes back first, so the log holds everything
  2. 2Agent startssession.status_running, run.startedThe agent picks up the brief as a run of kind brief
  3. 3Plan and toolsagent.message, agent.tool_use, agent.tool_resultIt says what it will do, searches the workspace for references, and picks a model
  4. 4Generationjob.started → job.completedA second session.status_running marks the agent resuming when the image is ready. job.completed carries outputs[].url and asset_id
  5. 5Replyagent.messageThe agent describes the finished image
  6. 6Wrap-uprun.completed, session.usageThe run closes and reports credits_charged
  7. 7Donesession.status_idlestop_reason end_turn: the agent is waiting for your next message
The agent decides which tools to call, so the middle of the log varies from brief to brief, and it may ask a question instead of generating. agent.message_delta frames stream the reply text while you are connected; they have no seq and are not replayed.

The job.completed event carries the result:

{
"type": "job.completed",
"seq": 14,
"job_id": "apijob_a95785b972bb4296",
"outputs": [
{
"type": "image",
"url": "https://…",
"asset_id": "XadkmWNE",
"mime": "image/png",
"width": 2048,
"height": 2048
}
],
"credits_charged": 35
}

The URL is presigned and expires; keep the asset_id to refer to the image later.

You created a workspace for one customer, opened a session capped at 2,000 credits, and sent a brief. The agent searched the workspace, chose a model, generated the image and reported every step on one numbered log. This run charged 35 credits.