--- title: Instructions and references | Luma Agents description: 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](/agents/skills/index.md) pinned to the session | The session’s life | | Fonts | `/v1/fonts`, per team or per workspace | Until you delete them | ## Standing instructions `system_context` is text the agent follows on every turn, up to 8,192 characters. Set it when you create the session. - [cURL](#tab-panel-0-0) - [Python](#tab-panel-0-1) - [TypeScript](#tab-panel-0-2) ```bash 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) ``` ```python import json import mimetypes import os import time import urllib.request import 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"] ``` ```typescript import { readFile } from "node:fs/promises"; const BASE = "https://agents.lumalabs.ai/v1"; async function post( path: string, body: unknown, token: string, headers: Record = {}, ) { 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 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. 1**Upload**`POST /v1/attachments`Send the file with the session id 2. 2**Wait**`state: ready`Poll until Luma has checked it 3. 3**Use**`attachment_ids`Name it on a user.message - [cURL](#tab-panel-1-0) - [Python](#tab-panel-1-1) - [TypeScript](#tab-panel-1-2) ```bash 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" } ] }' ``` ```python 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, ) ``` ```typescript 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 | PDF | | 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](/agents/workflow-apps/index.md), pass attachment ids in the app’s own form fields rather than on a message. See [Workflow apps](/agents/workflow-apps/index.md). ## 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](/agents/skills/index.md) 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. ## Fonts 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. Uploading a font does not change what the image models draw. Generated images keep the model’s own lettering. Fonts are for setting text yourself. When you [layer an image](/agents/more/index.md), 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](#tab-panel-2-0) - [Python](#tab-panel-2-1) - [TypeScript](#tab-panel-2-2) ```bash 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 '{}' ``` ```python 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) ``` ```typescript 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 - 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:`, `font_family:`). 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. ## Next - [Skills](/agents/skills/index.md): write reusable guidance once. - [Workspaces and access](/agents/workspaces/index.md): where a session’s files are stored.