/brand-assistant while signed in. All authenticated workspace members can use the assistant without a separate Brand allowlist entry. Each chat belongs to its user and workspace, including personal workspaces. Switch workspaces to see that workspace’s chats and balance. Rename or archive chats from their header; archived history remains saved. Model and generation work require sufficient credits in the active workspace; opening the page and managing chats do not spend model credits.
Guided setup and draft references
Choose one of the six app cards to open its first input question without a model call, or start a free-form conversation. New chats open immediately and save in the background. Each chat keeps its own draft, upload and running state, so another chat can be started while work continues. Selecting an app uses that app’s current input definitions, including optional styling, colours and lighting. The assistant asks one question at a time, accepts several answers or corrections in ordinary chat, and saves the choices with the conversation. The setup summary lets users revisit choices. An unrelated question does not discard the setup. App defaults and optional skips are explicit choices; generation still requires its own review and approval. API clients may create a guided chat withappKey and a stable clientChatId on POST /chats, or read its verified choices with GET /apps/{appKey}/intake. Retry an interrupted chat save with the same clientChatId; only the same authenticated principal can recover it. API clients may also include appKey on a turn to select one of fashion_catalog, catalog_upgrade, product_banners, virtual_try_on, apparel_ad_video, or non_apparel_ad_video. Later turns can omit it. The saved conversation.task_state.guidedIntake contains the selected app, current fields and answers; it is retained separately from compacted model history. No source app workflow is edited.
Select up to eight attachments per message. The web composer keeps files on the device with small removable/replaceable thumbnails until Send. On Send it uploads and verifies them before starting the assistant. Image uploads require consent for public reference links; PDF/text documents remain private. An interrupted upload retains the draft and reuses confirmed upload progress on retry. Unsaved local files do not survive a page reload. Saved input images appear as small thumbnails in the user message; generated outputs remain larger. Clicking an input or output image opens the right-side preview.
Additional custom images
The assistant uses the six Brand apps first. When you request additional or custom still images outside an app’s fixed deliverables, it can use Lamina’s existing AI Image Generator through Brand MCP. New custom-image plans currently use NanoBanana 2 only, with your approved reference images. The UI shows a concise description, reference previews, one to four labelled outputs and estimated credits before approval. Full prompts and provider parameters remain in the saved plan/API for execution, and are not rendered in the chat UI. Outputs are saved in the same chat for preview and download. A person preset in a catalogue app is distinct from an AI image-generation model. Custom images use the same workspace credit pool and approval lifecycle over both the UI and this API. There are no standalone video, audio or general workflow tools; video requests continue through the Brand apps. A failed or uncertain request is not automatically rerun on another model. Custom stills can also supply missing reference images for a Brand app. Inspect that app’s input requirements, generate the prerequisite, and pass its verified output URL into the app’s normal assessment/preparation flow. Usesource_bindings: [{path: "product.images", value: [outputUrl], source: "generated", run_id: runId}] with the app’s actual reference field; the server checks run ownership and the exact completed image. Do not duplicate built-in prerequisites. Each paid plan needs its own review approval. The custom-image model is fixed to NanoBanana 2 for now; the assistant honors portrait/landscape requests and asks only about unresolved material choices. This restriction does not replace models configured inside the six Brand app workflows. Input image dimensions and final app output constraints are separate.
API authentication
The same lifecycle is available at/v1/brand-assistant with a Lamina workspace API key in x-api-key or Authorization: Bearer. An optional x-workspace-id must match the key. API chats belong to the key identity and cannot read its creator’s private browser chats. Current workspace membership and credential revocation are checked again during tool execution. The assistant exposes only Brand tools and scoped chat retrieval; general Lamina MCP tools are not connected. Direct Brand MCP callers retain their separate MCP authorization policy. Embed credentials are not accepted. OAuth is disabled unless an operator configures and validates a supported assistant audience; a Brand MCP OAuth token is not automatically an assistant API credential.
GET /capabilities (relative to /v1/brand-assistant) before sending paid work. It returns modelEnabled, generationEnabled, token prices and workspace balance, total_earned, total_spent. Read GET /chats/{chatId} for the current revision.
turnId and status. On a connection failure or queue_unavailable, retry the identical body and idempotency key. A changed body requires a new key; do not create a new key merely to recover delivery. Only one active turn is allowed per chat.
Use GET /progress?ids=<comma-separated UUIDs> to check up to twenty owned chats in one small read. Refresh a chat snapshot when its revision, sequence or active turn changes; slow down while idle or reconnecting. The web UI also listens for status notifications, with durable reads as fallback. Alternatively poll /chats/{chatId}/events?after=123 every four seconds while working. Event pages contain up to 100 items; advance using the last returned seq, and drain full pages before waiting. Reloads and reconnects read PostgreSQL-backed events, not an in-memory stream. Older history uses /items?before=123.
Preparation and approval
All six Brand apps share MCP’s describe → assess → prepare → execute → status lifecycle: Fashion Catalogue, Catalogue Photos and Video, Product Ad Banners, Virtual Try-On, Apparel Ad Video, and Product Ad Video. The assistant uses those same schemas and services inside OpenAI’s Agents SDK. A turn that requests generation pauses asawaiting_approval. Review the saved inputs, outputs, estimate and expiry. POST to /chats/{chatId}/approvals/{approvalId} with decision (approved or rejected), the saved planId, planFingerprint, maxCredits, and current expectedRevision. The server fixes execution’s idempotency key; clients and the model cannot replace it. Expired plans need new preparation; rejection remains possible after expiry.
maxCredits checks the generation estimate, not a hard provider spending cap. Assistant model spending has a separate reservation-backed maxAssistantCredits budget. Both debit the existing workspace credit ledger. Unused assistant reservations are refunded once; the ledger’s existing refund convention also affects total earned/spent. An uncertain provider outcome retains its reservation for reconciliation instead of silently repeating work.
The UI immediately displays sent messages with delivery feedback and keeps a visible progress indicator while the assistant or generation is active, including while status reconnects. After dispatch, /chats/{chatId}/runs/{runId} polls generation without another model call. A failed run may still contain verified usable images or videos. Keep those outputs and its retry guidance. recovery_blocked or needs_attention requires reconciliation; do not blindly start another paid run. Cancellation of a turn and cancellation of a generation are separate endpoints and cannot guarantee a refund.
Files and downloads
- POST
/chats/{chatId}/assetswithfilename,mimeType,byteSizeandpublicUploadAcceptedfor images. - PUT the file bytes to the returned signed
uploadUrlwith itscontentType. - POST
/chats/{chatId}/assets/{assetId}/finalizebefore attaching the ID to a message.
/chats/{chatId}/assets/{assetId}/download with header authentication for saved attachments and outputs. It verifies ownership and returns downloadable bytes. The UI previews images/videos, labels partial results, and offers download buttons.
Context and persistence
The model isgpt-6-sol with high reasoning effort. Complete visible history is separate from its working checkpoint. At 96,000 measured input tokens, a completed working window is compacted through OpenAI’s native Responses compaction; the entire returned continuation is retained, then the new request is appended. The safe input ceiling is 160,000 tokens and each response allows up to 16,000 output/reasoning tokens. These are Lamina operating limits, not a fixed message retention count.
Instructions, published craft skills, current plan/run state and authorized tools are reloaded each turn. Compaction never deletes saved messages. Scoped archive search recovers exact earlier wording; exact approvals, account identities, budgets and artifacts live outside summaries. Compaction is billed within the assistant budget and is not a promise of perfect recall. Provider-native opaque state stays on the server; it is not returned as reasoning.
Operator rollout and recovery
SetBRAND_ASSISTANT_ENABLED, BRAND_ASSISTANT_MODEL_ENABLED and BRAND_ASSISTANT_GENERATION_ENABLED independently. Existing MCP_COMMERCE_* permissions and verified contracts still apply. Token pricing must exist as active credit_cost_config.action_type = brand_assistant_gpt6_sol_high; there is no fallback price. Standard model pricing includes cached reads and cache writes; reasoning tokens are already included in output usage. Disable model/generation flags to inspect history without paid calls.
Workers have a fenced five-minute lease with heartbeats. Queue delivery can repeat, but a running turn cannot be claimed twice. Expired workers become needs_attention on reopening; provider-uncertain work is never automatically resent. Inspect saved request usage/response, approvals and the existing generation run before reconciling a held reservation. Reconciliation may call brand_assistant_settle only with confirmed usage and the captured pricing revision; this RPC is service-role-only and idempotent. Do not infer a refund from a timeout or aggregate workspace balance.
The complete route contract is published in /v1/openapi.json and the OpenAPI reference.
App recipes and persistent media
WithBRAND_COMMERCE_RECIPES_ENABLED=true, the assistant reads authorized Brand apps as creative recipes and assembles prompts itself. It prepares direct image/video steps with the app’s supported generator settings; it does not edit workflows or run prompt-builder LLM nodes. Additional custom stills use Nano Banana 2. Existing app/image plans and their saved outputs remain readable and executable under their original approvals.
Each new plan freezes source recipe/version/hash, complete brief, source media roles, exact prompts/settings, dependencies and price. A separate approval is required before generation. The user sees a concise description, deliverables and estimate. Raw prompts remain in server-side plans, not review cards. Optional video assembly concatenates reviewed clips deterministically; narration, new clips, effects and other hidden generation are excluded from that assembly operation.
Original product and person references, generated prerequisites and final outputs retain distinct identities. Working-context compaction does not remove their saved plans/assets. Each new turn reconstructs this media manifest from owned chat records; read_chat_media pages older assets, and archive tools retrieve exact earlier instructions. A generated background can feed a later image without replacing the original product photo. Stable saved asset/run identities are used rather than treating an expiring URL as memory.
The existing /v1/brand-assistant API uses the same chat, approval, credit and asset services as the UI. There is no workflow-copy endpoint. Disable the recipe flag to pause new recipe preparation while preserving saved history and status reconciliation.
Conversation timeline and previews
Approvals remain in the chat after a decision, collapsed with their description and estimate. Generated references and final outputs are attached to their originating turn in step order; they are not appended to a shared gallery. Running generations keep a visible status until terminal confirmation. Clicking an output or its Preview action opens the right-side preview with Download. Failed remote previews recover through the same authenticated asset-download endpoint; recovery never repeats generation. Snapshot and paginateditems responses include the approvals and assets associated with their event window. Clients should merge these records by ID when loading earlier history and refreshing, so older decisions and media stay available.
Preparation and generation progress
The assistant can read selected output recipes in bounded bundles instead of repeated outline/detail calls. Savedturn.phase items describe preparation without exposing prompts. Generation status reports the number ready and currently generating; each completed image retains its place in the conversation and its preview/download controls. Opening a saved chat restores this status without a model request.
Operators can enable bounded parallel Brand recipe execution with BRAND_RECIPE_PARALLEL_ENABLED=true and BRAND_RECIPE_MAX_CONCURRENCY=3 on the environment’s service handling /api/jobs/lamina/agentPipelineRun. Dependencies, exact reviewed settings, workspace billing and approval remain enforced. Set the enable flag to false to limit new dispatches to one; existing concurrent requests are still checked and settled. This flag does not change general Lamina or Cinematic Story scheduling.