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.
| Input | Where it goes | Lasts |
|---|---|---|
| Standing instructions | system_context on the session | Every turn |
| Reference files | attachment_ids on a message | Stored in the workspace |
| Existing assets | asset_ids on a message | Already in the workspace |
| Reusable guidance | A skill pinned to the session | The session’s life |
| Fonts | /v1/fonts, per team or per workspace | Until you delete them |
Standing instructions
Section titled “Standing instructions”system_context is text the agent follows on every turn, up to 8,192 characters. Set it when you create the session.
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)import jsonimport mimetypesimport osimport timeimport urllib.requestimport uuid
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)
session_id = post( "/sessions", { "scope_id": workspace_id, "system_context": "Warm, rustic look. Natural light only. Never show people.", }, session_token,)["session_id"]import { readFile } from "node:fs/promises";
const BASE = "https://agents.lumalabs.ai/v1";
async function post( path: string, body: unknown, token: string, headers: Record<string, string> = {},) { 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 { session_id: sessionId } = await post( "/sessions", { scope_id: workspaceId, system_context: "Warm, rustic look. Natural light only. Never show people.", }, sessionToken,);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.
Reference files
Section titled “Reference files”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.
- 1Upload
POST /v1/attachmentsSend the file with the session id - 2Wait
state: readyPoll until Luma has checked it - 3Use
attachment_idsName it on a user.message
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" } ] }'def upload(path, file_path, token): boundary = uuid.uuid4().hex name = os.path.basename(file_path) mime = mimetypes.guess_type(name)[0] or "application/octet-stream" with open(file_path, "rb") as f: content = f.read() body = ( f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="{name}"\r\n' f"Content-Type: {mime}\r\n\r\n" ).encode() + content + f"\r\n--{boundary}--\r\n".encode() request = urllib.request.Request( BASE + path, method="POST", data=body, headers={"Authorization": f"Bearer {token}", "Content-Type": f"multipart/form-data; boundary={boundary}"}, ) with urllib.request.urlopen(request) as response: return json.load(response)
attachment_id = upload(f"/attachments?session_id={session_id}", "logo.png", session_token)["attachment_id"]
# poll until "state" is "ready"state = get(f"/attachments/{attachment_id}?session_id={session_id}", session_token)["state"]while state == "pipeline_running": time.sleep(2) state = get(f"/attachments/{attachment_id}?session_id={session_id}", session_token)["state"]print(state)
post( f"/sessions/{session_id}/events", {"events": [{ "type": "user.message", "content": "Put our logo in the bottom-right corner of each banner.", "attachment_ids": [attachment_id], "idempotency_key": "msg-7732", }]}, session_token,)const form = new FormData();form.append( "file", new Blob([await readFile("logo.png")], { type: "image/png" }), "logo.png",);const uploaded = await fetch(`${BASE}/attachments?session_id=${sessionId}`, { method: "POST", headers: { Authorization: `Bearer ${sessionToken}` }, body: form,});if (!uploaded.ok) throw new Error(`${uploaded.status} ${await uploaded.text()}`);const { attachment_id: attachmentId } = await uploaded.json();
// poll until "state" is "ready"let { state } = await get( `/attachments/${attachmentId}?session_id=${sessionId}`, sessionToken,);while (state === "pipeline_running") { await new Promise((resolve) => setTimeout(resolve, 2000)); ({ state } = await get( `/attachments/${attachmentId}?session_id=${sessionId}`, sessionToken, ));}console.log(state);
await post( `/sessions/${sessionId}/events`, { events: [ { type: "user.message", content: "Put our logo in the bottom-right corner of each banner.", attachment_ids: [attachmentId], idempotency_key: "msg-7732", }, ], }, sessionToken,);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.
| Kind | Accepted types |
|---|---|
| Images | JPEG, PNG, WebP, GIF |
| Documents | |
| Data | CSV |
| Video | MP4, 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.
Reusable guidance
Section titled “Reusable guidance”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.
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 '{}'slot = post( "/fonts/uploads", {"file_name": "AcmeSans-Bold.woff2", "size": 48213, "scope_id": workspace_id}, session_token,)# PUT the file to slot["presigned_url"], then:post(f"/fonts/uploads/{slot['face_id']}/complete", {}, session_token)const slot = await post( "/fonts/uploads", { file_name: "AcmeSans-Bold.woff2", size: 48213, scope_id: workspaceId }, sessionToken,);// PUT the file to slot.presigned_url, then:await post(`/fonts/uploads/${slot.face_id}/complete`, {}, sessionToken);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.
Details
Section titled “Details”- 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 samesession_idas the upload. - The rejections
content_moderated,file_too_large,video_too_long,corrupt_input,empty,mime_mismatchandunsupported_formatneed a different file.processing_timeoutandinternal_errorare on Luma’s side; upload again. - Font files can be
.ttf,.otf,.woffor.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_idand copy what you keep to your own storage as soon as it lands.
- Skills: write reusable guidance once.
- Workspaces and access: where a session’s files are stored.