Skip to content

Instructions and references

Give a session standing instructions and reference files, such as a brand guide, so every result follows them.

Everything on this page is optional. A session works from a brief alone. Pass these inputs when you want outputs to follow a style, a set of rules or your customer’s brand.

InputWhere it goesLasts
Standing instructionssystem_context on the sessionEvery turn
Reference filesattachment_ids on a messageStored in the workspace
Existing assetsasset_ids on a messageAlready in the workspace
Reusable guidanceA skill pinned to the sessionThe session’s life
Fonts/v1/fonts, per team or per workspaceUntil you delete them

system_context is text the agent follows on every turn, up to 8,192 characters. Set it when you create the session.

Terminal window
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"'",
"system_context": "Warm, rustic look. Natural light only. Never show people."
}' \
| jq -r .session_id)

Keep it to rules that hold for every request. Put the request itself in the message. A tighter system_context also tends to mean fewer turns, which lowers what a brief costs.

Upload a file to the session, wait until it is ready, then name it on a message. Product photos, logos, a mood board or a PDF brief all work the same way.

  1. 1UploadPOST /v1/attachmentsSend the file with the session id
  2. 2Waitstate: readyPoll until Luma has checked it
  3. 3Useattachment_idsName it on a user.message
Terminal window
ATTACHMENT_ID=$(curl -s -X POST "https://agents.lumalabs.ai/v1/attachments?session_id=$SESSION_ID" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-F "file=@logo.png" | jq -r .attachment_id)
# poll until "state" is "ready"
curl -s "https://agents.lumalabs.ai/v1/attachments/$ATTACHMENT_ID?session_id=$SESSION_ID" \
-H "Authorization: Bearer $SESSION_TOKEN" | jq -r .state
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": "Put our logo in the bottom-right corner of each banner.",
"attachment_ids": ["'"$ATTACHMENT_ID"'"],
"idempotency_key": "msg-7732"
} ] }'

No event tells you an attachment is ready, so poll. A file can also come back rejected, on the upload itself or on a later poll; rejection_reason says why. An attachment stays in the workspace, so later sessions there can find it too.

KindAccepted types
ImagesJPEG, PNG, WebP, GIF
DocumentsPDF
DataCSV
VideoMP4, MOV, WebM

To reuse something the agent already made, pass its asset_id in asset_ids on the message instead.

For a workflow app, pass attachment ids in the app’s own form fields rather than on a message. See Workflow apps.

When the same guidance applies across many sessions, such as a customer’s voice and visual rules, write it once as a skill and pin it on each session with skills. A skill can be shared by all your workspaces or belong to one. A session can’t pin skills and run an app at the same time; an app’s guidance comes from the app.

Upload a customer’s font files once, for your whole team or for one workspace, and Luma reads each file’s family, weight and style.

Fonts are for setting text yourself. When you layer an image, a text layer can name the closest uploaded face, so you can hide that layer and set its words as live type in the brand face. Each face can also be downloaded for your own renderer.

An upload takes three calls: ask for a slot, upload the bytes, then complete it.

Terminal window
curl -s -X POST https://agents.lumalabs.ai/v1/fonts/uploads \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "file_name": "AcmeSans-Bold.woff2", "size": 48213, "scope_id": "'"$WORKSPACE_ID"'" }'
# PUT the file to the returned presigned_url, then:
curl -s -X POST https://agents.lumalabs.ai/v1/fonts/uploads/$FACE_ID/complete \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" -d '{}'

With a session token you must name a scope_id, and the font belongs to that workspace. With the API key and no scope_id, the font joins your team’s library and every workspace sees it. GET /v1/fonts?scope_id=$WORKSPACE_ID lists what one workspace sees.

  • Images, PDFs and CSVs up to 50 MB. Keep a CSV under 8 MB for the agent to work with it as data. Other types answer 415 ATTACHMENT.UNSUPPORTED_TYPE. The poll needs the same session_id as the upload.
  • The rejections content_moderated, file_too_large, video_too_long, corrupt_input, empty, mime_mismatch and unsupported_format need a different file. processing_timeout and internal_error are on Luma’s side; upload again.
  • Font files can be .ttf, .otf, .woff or .woff2, up to 20 MB each, 500 faces per team. Ids are typed (font_face:<uuid>, font_family:<uuid>). A workspace family hides a team family of the same name in that workspace. Deleting a workspace deletes its fonts.
  • Output URLs last one hour and Luma doesn’t guarantee how long outputs stay fetchable. Store asset_id and copy what you keep to your own storage as soon as it lands.