{"openapi":"3.1.0","info":{"title":"Lumavox API","version":"0.58.6","description":"Speech, conversation and generative media: text to speech and transcription,\nvoices, images, video, 360° skyboxes, and agents that hold a conversation\nserver-side.\n\n**Everything this reference does not say is in the docs, https://docs.lumavox.ai** —\nauthentication and scopes, queued jobs, audio formats, errors and limits, and\nthe agent's WebSocket, which OpenAPI cannot describe. An agent should start\nat https://docs.lumavox.ai/llms.txt: every page is Markdown at its address plus `.md`.\n\nOperations take a token — `Authorization: Bearer `, or\n`X-API-Key: ` — but for the few marked otherwise. Keep API keys on\nyour server; an agent's conversations take an end user's ephemeral token\ninstead.\n"},"tags":[{"name":"tts","description":"Speech generation"},{"name":"images","description":"Image generation"},{"name":"videos","description":"Video generation"},{"name":"skybox","description":"360° environments — an 8K HDRI for lighting a 3D scene, an equirectangular PNG and a depth map. One flat price per generation, whatever you ask for"},{"name":"templates","description":"Generations somebody has already designed — the prompt, the size, every parameter — leaving only the media inputs for you to fill. Priced up front, and polled on the capability's own endpoint"},{"name":"audio","description":"Speech as a queued generation — stored, and the only door that encodes mp3 or opus"},{"name":"transcription","description":"Speech to text — inline for short audio, `stream=true` for newline-delimited segments, queued for long"},{"name":"voices","description":"The voices a key may speak with, and — on `voices:write` — adding, designing, editing and deleting your own"},{"name":"agents","description":"Authoring agents: the characters `/v1/agent/*` talks to, their organisation-wide defaults, and what each may look up. Reads on `agent`, writes on `agent:write`"},{"name":"knowledge","description":"What you tell your agents — entries an agent can look up by meaning, written and assigned from your own systems"},{"name":"tools","description":"What your agents can call while they reply — your server, signed, or the person's app over the WebSocket — each turned on per agent. Reads on `agent`, writes on `agent:write`"},{"name":"agent","description":"Conversations with an agent. There is a streaming door too, on a WebSocket that OpenAPI cannot describe — see *The WebSocket* in the docs"},{"name":"assets","description":"The library — everything your services have produced and you have uploaded. Reads and uploads on `assets`; renaming, moving, deleting and folders on `assets:write`"},{"name":"generations","description":"Every generation across every capability, in one list — the way back to an id you lost, and the reconciliation loop"},{"name":"usage","description":"What your organisation has spent, and what it has left"},{"name":"end users","description":"The people your agents talk to and you generate on behalf of"},{"name":"ephemeral keys","description":"Short-lived tokens for one end user's device, with their own credit ceiling"},{"name":"system","description":"Health and metadata"}],"security":[{"BearerToken":[]},{"ApiKeyHeader":[]}],"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"version":{"type":"string","description":"The API's version.","examples":["0.35.0"]}},"required":["status","version"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorInfo"}},"required":["error"]},"ErrorInfo":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"What went wrong, in words"},"request_id":{"type":"string","description":"Echo of `X-Request-Id` — include it when reporting a problem"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"},"description":"Where the request failed validation; empty otherwise"}},"required":["code","message","request_id","issues"]},"ErrorCode":{"type":"string","enum":["invalid_request","unauthenticated","insufficient_credits","forbidden","waitlisted","not_found","method_not_allowed","conflict","too_large","validation_failed","rate_limited","internal","provider_failed","unavailable"],"description":"What went wrong, for a client to switch on: one per HTTP status, except `waitlisted`, a 403 of its own. New codes may be added."},"ValidationIssue":{"type":"object","properties":{"location":{"type":"string","enum":["body","query","path","header"]},"field":{"type":["string","null"],"description":"The dotted path to the field (`voice_config.sample_rate`, `agent_ids.2`); `null` for the whole body."},"message":{"type":"string"}},"required":["location","field","message"]},"PlatformLimitPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlatformLimit"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"PlatformLimit":{"type":"object","properties":{"key":{"type":"string","description":"The limit's name, which this reference's descriptions use for it.","examples":["limits.agent.tools"]},"label":{"type":"string","description":"What it limits, in words.","examples":["Tools on one agent"]},"value":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"boolean"}],"description":"The limit in force now, in `unit`.","examples":[20]},"unit":{"type":["string","null"],"enum":["ms","seconds","minutes","hours","days","bytes","credits",null],"description":"What `value` counts; null for a plain count. `credits` are whole credits, not micro-credits."},"default":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"boolean"}],"description":"The platform's built-in value, which `value` may differ from.","examples":[20]}},"required":["key","label","value","unit","default"]},"TemplateInput":{"type":"object","properties":{"slot":{"type":"string","description":"What to name it in `inputs` when generating.","examples":["reference_1","start_frame","prompt"]},"kind":{"type":"string","enum":["image","text"],"description":"`image` takes an `ast_…` id from your library; `text` takes what you type — the prompt, when the template leaves it to you."},"label":{"type":"string"},"hint":{"type":["string","null"]},"required":{"type":"boolean"},"example_url":{"type":["string","null"],"description":"For an image input: a picture of the kind of thing that belongs here — the one the example output was generated from."},"example":{"type":["string","null"],"description":"For a text input: an example of what to write — the text the example output was generated from."}},"required":["slot","kind","label","hint","required","example_url","example"]},"SkyboxStylePage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SkyboxStyle"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"SkyboxStyle":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"max_prompt_chars":{"type":["integer","null"]},"max_negative_chars":{"type":["integer","null"]},"model_version":{"type":["string","null"],"description":"Which of the provider's model generations it runs on."},"image":{"type":["string","null"],"description":"A sample image of the style, if they gave one."}},"required":["id","name","max_prompt_chars","max_negative_chars","model_version","image"]},"EphemeralKeyLimits":{"type":"object","properties":{"max_ttl_seconds":{"type":"integer","description":"The platform's longest lifetime for a key."},"default_ttl_seconds":{"type":"integer"},"max_credit_limit_micros":{"type":"integer","description":"The platform's largest credit limit for a key.","examples":[2500000]},"plan_max_ttl_seconds":{"type":["integer","null"],"description":"Your plan's longest lifetime for one end user's key; `null` sets none. A key is held to the tighter of this and `max_ttl_seconds`."},"plan_max_credit_limit_micros":{"type":["integer","null"],"description":"Your plan's largest credit limit for one end user's key, in micro-credits; `null` sets none. A key is held to the tighter of this and `max_credit_limit_micros`."},"plan_max_live_keys":{"type":["integer","null"],"description":"How many live keys one end user may hold on your plan; `null` sets none."},"grantable_scopes":{"type":"array","items":{"type":"string"}}},"required":["max_ttl_seconds","default_ttl_seconds","max_credit_limit_micros","plan_max_ttl_seconds","plan_max_credit_limit_micros","plan_max_live_keys","grantable_scopes"]},"EphemeralKeyCreateResponse":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":["string","null"]},"prefix":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"credit_limit_micros":{"type":"integer","description":"The most this key may spend, in micro-credits.","examples":[2500000]},"credits_spent_micros":{"type":"integer","description":"What it has spent, as its end user DO last settled — at the end, or daily for a long-lived key. Final once `settled_at` is set.","examples":[2500000]},"credits_remaining_micros":{"type":"integer","description":"Micro-credits: 1 credit is 1,000,000.","examples":[2500000]},"agent_ids":{"type":["array","null"],"items":{"type":"string"}},"created_by_api_key_id":{"type":["string","null"]},"created_by_clerk_user_id":{"type":["string","null"]},"end_user_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"expires_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"last_used_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"revoked_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"revoked_reason":{"type":["string","null"]},"settled_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"],"description":"When its end user DO settled it for the last time — what it spent and what came back are final from then. `null` while it is live, and for a few seconds after it ends, longer while a memory job it paid for still runs."},"active":{"type":"boolean"},"key":{"type":"string","description":"The token, in full. **Shown once**: it is signed rather than stored, so it cannot be shown again."}},"required":["id","label","prefix","last4","scopes","credit_limit_micros","credits_spent_micros","credits_remaining_micros","agent_ids","created_by_api_key_id","created_by_clerk_user_id","end_user_id","created_at","expires_at","last_used_at","revoked_at","revoked_reason","settled_at","active","key"]},"EphemeralKeyCreateRequest":{"type":"object","properties":{"scopes":{"type":"array","items":{"type":"string"},"default":["agent"]},"credit_limit_micros":{"type":"integer","exclusiveMinimum":0,"description":"The most this key may spend, in micro-credits (1 credit is 1,000,000). Required — there is no unlimited key."},"expires_in_seconds":{"type":"integer","exclusiveMinimum":0,"default":900},"end_user_id":{"type":"string"},"agent_ids":{"type":["array","null"],"items":{"type":"string"},"default":null},"label":{"type":["string","null"],"maxLength":120,"default":null}},"required":["credit_limit_micros","end_user_id"],"additionalProperties":false},"EphemeralKeyPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EphemeralKeyInfo"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"EphemeralKeyInfo":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":["string","null"]},"prefix":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"credit_limit_micros":{"type":"integer","description":"The most this key may spend, in micro-credits.","examples":[2500000]},"credits_spent_micros":{"type":"integer","description":"What it has spent, as its end user DO last settled — at the end, or daily for a long-lived key. Final once `settled_at` is set.","examples":[2500000]},"credits_remaining_micros":{"type":"integer","description":"Micro-credits: 1 credit is 1,000,000.","examples":[2500000]},"agent_ids":{"type":["array","null"],"items":{"type":"string"}},"created_by_api_key_id":{"type":["string","null"]},"created_by_clerk_user_id":{"type":["string","null"]},"end_user_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"expires_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"last_used_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"revoked_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"revoked_reason":{"type":["string","null"]},"settled_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"],"description":"When its end user DO settled it for the last time — what it spent and what came back are final from then. `null` while it is live, and for a few seconds after it ends, longer while a memory job it paid for still runs."},"active":{"type":"boolean"}},"required":["id","label","prefix","last4","scopes","credit_limit_micros","credits_spent_micros","credits_remaining_micros","agent_ids","created_by_api_key_id","created_by_clerk_user_id","end_user_id","created_at","expires_at","last_used_at","revoked_at","revoked_reason","settled_at","active"]},"TokenSelf":{"oneOf":[{"$ref":"#/components/schemas/EphemeralTokenSelf"},{"$ref":"#/components/schemas/ApiKeySelf"}],"discriminator":{"propertyName":"kind","mapping":{"ephemeral":"#/components/schemas/EphemeralTokenSelf","api_key":"#/components/schemas/ApiKeySelf"}}},"EphemeralTokenSelf":{"type":"object","properties":{"kind":{"type":"string","enum":["ephemeral"]},"scopes":{"type":"array","items":{"type":"string"}},"credit_limit_micros":{"type":"integer","description":"Micro-credits: 1 credit is 1,000,000.","examples":[2500000]},"credits_spent_micros":{"type":"integer","description":"What the key has spent so far, turn by turn.","examples":[2500000]},"credits_remaining_micros":{"type":"integer","description":"Micro-credits: 1 credit is 1,000,000.","examples":[2500000]},"expires_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"expires_in_seconds":{"type":"integer"},"agent_ids":{"type":["array","null"],"items":{"type":"string"}},"end_user_id":{"type":["string","null"]}},"required":["kind","scopes","credit_limit_micros","credits_spent_micros","credits_remaining_micros","expires_at","expires_in_seconds","agent_ids","end_user_id"]},"ApiKeySelf":{"type":"object","properties":{"kind":{"type":"string","enum":["api_key"]},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"is_master":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]}},"required":["kind","name","scopes","is_master","created_at"]},"UsageResponse":{"type":"object","properties":{"org_id":{"type":"string"},"since":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"until":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"plan":{"anyOf":[{"$ref":"#/components/schemas/OrgPlan"},{"type":"null"}],"description":"The organisation's subscription and remaining credits, or null if it is not on a plan."},"total_requests":{"type":"integer"},"total_seconds":{"type":"number"},"by_capability":{"type":"array","items":{"$ref":"#/components/schemas/UsageSummary"}},"daily":{"type":"array","items":{"$ref":"#/components/schemas/UsageDay"},"description":"One entry per UTC day across the whole window, **including days with no traffic**. Gap-filled server-side so a chart can plot it directly rather than every client reinventing the same fill."},"by_key":{"type":"array","items":{"$ref":"#/components/schemas/UsageByKey"},"description":"Which credential spent the quota, busiest first."}},"required":["org_id","since","until","plan","total_requests","total_seconds","by_capability","daily","by_key"]},"OrgPlan":{"type":"object","properties":{"plan_slug":{"type":"string"},"plan_name":{"type":"string"},"monthly_credits_micros":{"type":"integer","description":"What the plan grants each cycle.","examples":[2500000]},"credit_balance_micros":{"type":"integer","description":"What is left: may exceed the grant after a manual adjustment, and be slightly negative inside the grace buffer.","examples":[2500000]},"period_end":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]}},"required":["plan_slug","plan_name","monthly_credits_micros","credit_balance_micros","period_end"]},"UsageSummary":{"type":"object","properties":{"capability":{"type":"string"},"model":{"type":["string","null"]},"event_type":{"type":["string","null"]},"requests":{"type":"integer"},"units_seconds":{"type":"number"},"credits_micros":{"type":["integer","null"],"description":"What was charged; null when nothing in the group was priced.","examples":[2500000]},"unpriced_requests":{"type":"integer","description":"Requests in this group with no price recorded. Their credits are not in the sum, so a non-zero value here means the total is a floor."}},"required":["capability","model","event_type","requests","units_seconds","credits_micros","unpriced_requests"]},"UsageDay":{"type":"object","properties":{"date":{"type":"string","format":"date"},"requests":{"type":"integer"},"units_seconds":{"type":"number"}},"required":["date","requests","units_seconds"]},"UsageByKey":{"type":"object","properties":{"api_key_id":{"type":["string","null"],"description":"Null once the key has been deleted"},"name":{"type":"string","description":"Key label, or 'Deleted key' if it is gone"},"requests":{"type":"integer"},"units_seconds":{"type":"number"},"credits_micros":{"type":["integer","null"],"description":"What was charged; null when nothing in the group was priced.","examples":[2500000]},"unpriced_requests":{"type":"integer","description":"Requests in this group with no price recorded. Their credits are not in the sum, so a non-zero value here means the total is a floor."}},"required":["api_key_id","name","requests","units_seconds","credits_micros","unpriced_requests"]},"GenerationInfo":{"type":"object","properties":{"id":{"type":"string","description":"`gen_…`. Poll this.","examples":["gen_a1B2c3D4e5F6g7H8"]},"status":{"type":"string","enum":["queued","submitted","running","succeeded","failed","moderated"],"description":"`queued`, `submitted` and `running` mean keep polling. `succeeded`, `failed` and `moderated` are terminal — stop."},"capability":{"type":"string","enum":["tts","image","video","stt","skybox"]},"model":{"type":["string","null"]},"prompt":{"type":["string","null"]},"aspect_ratio":{"type":["string","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"output_format":{"type":["string","null"]},"seed":{"type":["integer","null"]},"megapixels":{"type":["number","null"]},"safety_tolerance":{"type":["integer","null"]},"enhance_prompt":{"type":["boolean","null"]},"folder_id":{"type":["string","null"],"description":"`fld_…` the result lands in, or null for the root."},"duration":{"type":["integer","null"],"description":"Seconds asked for. Video only."},"resolution":{"type":["string","null"],"description":"`hd` or `fhd`. Video only."},"generate_audio":{"type":["boolean","null"]},"start_frame":{"type":["string","null"]},"end_frame":{"type":["string","null"]},"negative_text":{"type":["string","null"]},"style_id":{"type":["integer","null"]},"init_image":{"type":["string","null"]},"init_strength":{"type":["number","null"]},"voice_id":{"type":["string","null"]},"speech":{"anyOf":[{"$ref":"#/components/schemas/TTSOptions"},{"type":"null"}],"description":"The voice and model a speech generation ran with."},"credits_micros":{"type":["integer","null"],"description":"What was debited when this was accepted, in micro-credits (1 credit is 1,000,000). A failure refunds it in full; a transcription's is corrected to the measured length when it finishes.","examples":[2500000]},"template_id":{"type":["string","null"]},"image":{"anyOf":[{"$ref":"#/components/schemas/GenerationImage"},{"type":"null"}]},"video":{"anyOf":[{"$ref":"#/components/schemas/GenerationVideo"},{"type":"null"}]},"audio":{"anyOf":[{"$ref":"#/components/schemas/GenerationAudio"},{"type":"null"}]},"transcript":{"anyOf":[{"$ref":"#/components/schemas/GenerationTranscript"},{"type":"null"}]},"skybox":{"anyOf":[{"$ref":"#/components/schemas/GenerationSkybox"},{"type":"null"}]},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"finished_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"]}},"required":["id","status","capability","model","prompt","aspect_ratio","width","height","output_format","seed","megapixels","safety_tolerance","enhance_prompt","folder_id","duration","resolution","generate_audio","start_frame","end_frame","negative_text","style_id","init_image","init_strength","voice_id","speech","credits_micros","template_id","image","video","audio","transcript","skybox","error","created_at","finished_at"]},"TTSOptions":{"type":"object","properties":{"voice_id":{"type":"string","description":"An id from `GET /v1/voices` — the built-in voice, a platform voice, or one your organisation uploaded."},"model":{"type":"string","description":"Which model speaks: one of the voice's `models` in `GET /v1/voices` — `eleven_flash_v2_5` (the fastest, and the default), `eleven_multilingual_v2` or `eleven_v3`. A model the voice does not list is refused."},"provider_options":{"anyOf":[{"$ref":"#/components/schemas/ProviderVoiceSettingsInfo"},{"type":"null"}],"description":"The provider's voice settings sent on top of the voice's own; `null` took theirs."},"format":{"type":"string","enum":["wav","pcm"]},"sample_rate":{"type":["integer","null"],"enum":[8000,16000,22050,24000,44100,null],"description":"Hz of the returned audio — one of 8000, 16000, 22050, 24000, 44100, each served natively by the provider. Unset means 24000.\n\n`POST /v1/tts` says what it produced in the `X-Sample-Rate` header. Queued speech (`POST /v1/audio`) does not take it: each of its formats has its own rate."}},"required":["voice_id","model","provider_options","format","sample_rate"]},"ProviderVoiceSettingsInfo":{"type":"object","properties":{"stability":{"type":["number","null"],"description":"Low is more expressive and less consistent between generations; high is flatter and more repeatable."},"similarity_boost":{"type":["number","null"],"description":"How closely to cling to the original voice. High can reproduce artefacts in the source."},"style":{"type":["number","null"],"description":"Style exaggeration. Costs latency; leave unset on anything conversational."},"use_speaker_boost":{"type":["boolean","null"],"description":"Similarity at the cost of latency."},"speed":{"type":["number","null"],"description":"1.0 is the voice's own pace."}},"required":["stability","similarity_boost","style","use_speaker_boost","speed"]},"GenerationImage":{"type":"object","properties":{"asset_id":{"type":["string","null"],"description":"The library entry this generation produced."},"url":{"type":["string","null"],"description":"A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one."},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]},"size_bytes":{"type":["integer","null"]}},"required":["asset_id","url","width","height","content_type","size_bytes"]},"GenerationVideo":{"type":"object","properties":{"asset_id":{"type":["string","null"],"description":"The library entry this generation produced."},"url":{"type":["string","null"],"description":"A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one."},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"duration_seconds":{"type":["number","null"]},"content_type":{"type":["string","null"]},"size_bytes":{"type":["integer","null"]},"has_thumbnail":{"type":["boolean","null"]}},"required":["asset_id","url","width","height","duration_seconds","content_type","size_bytes","has_thumbnail"]},"GenerationAudio":{"type":"object","properties":{"asset_id":{"type":["string","null"],"description":"The library entry this generation produced."},"url":{"type":["string","null"],"description":"A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one."},"duration_seconds":{"type":["number","null"]},"content_type":{"type":["string","null"]},"size_bytes":{"type":["integer","null"]},"peaks":{"type":["array","null"],"items":{"type":"integer"},"description":"Waveform magnitudes, 0-100, for a mirrored strip; null when never computed."}},"required":["asset_id","url","duration_seconds","content_type","size_bytes","peaks"]},"GenerationTranscript":{"type":"object","properties":{"text":{"type":["string","null"],"description":"The transcript, as one string."},"language_code":{"type":["string","null"]},"language_probability":{"type":["number","null"]},"duration_seconds":{"type":["number","null"]},"word_count":{"type":["integer","null"]},"asset_id":{"type":["string","null"],"description":"The library entry holding the full JSON."},"content_type":{"type":["string","null"]},"size_bytes":{"type":["integer","null"]},"url":{"type":["string","null"]}},"required":["text","language_code","language_probability","duration_seconds","word_count","asset_id","content_type","size_bytes","url"]},"GenerationSkybox":{"type":"object","properties":{"asset_id":{"type":["string","null"],"description":"The library entry this generation produced."},"url":{"type":["string","null"],"description":"A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one."},"preview_url":{"type":["string","null"],"description":"A short-lived link to the 2K WebP, which is what to load in a 360 viewer."},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"content_type":{"type":["string","null"]},"size_bytes":{"type":["integer","null"]},"has_thumbnail":{"type":["boolean","null"]},"files":{"type":"array","items":{"$ref":"#/components/schemas/SkyboxFile"},"description":"Every file the environment was stored as, in plan order."}},"required":["asset_id","url","preview_url","width","height","content_type","size_bytes","has_thumbnail","files"]},"SkyboxFile":{"type":"object","properties":{"name":{"type":"string","description":"`hdr-4k`, `hdr-2k`, `png-8k`, `png-4k`, `png-2k`, `preview-2k`, `depth-2k`.","examples":["hdr-4k"]},"content_type":{"type":"string"},"url":{"type":["string","null"],"description":"Short-lived link. Minted per response and not stored."},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"size_bytes":{"type":["integer","null"]}},"required":["name","content_type","url","width","height","size_bytes"]},"ImageRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":4000,"description":"What to generate.","examples":["A weathered brass diving helmet on wet slate, low winter light"]},"aspect_ratio":{"type":"string","default":"1:1","description":"One of: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16."},"megapixels":{"type":"number","minimum":0.25,"maximum":4,"default":1,"description":"Output size. **This and your references are what you are charged on** — the price is per megapixel, the output's with a one-megapixel minimum and each reference's at the same rate on its own size, so a request's cost is known before it is made."},"output_format":{"type":"string","default":"jpeg","description":"One of: jpeg, png, webp."},"seed":{"type":["integer","null"],"minimum":0,"description":"Reuse a seed to get the same image again from the same prompt. Omit for a different one each time."},"safety_tolerance":{"type":"integer","minimum":0,"maximum":5,"default":2,"description":"0 is strictest. Content refused at any setting is refused."},"enhance_prompt":{"type":"boolean","default":true,"description":"Let the model rewrite your prompt before rendering. On by default, which is the provider's own behaviour. Turn it off to send your words exactly as written."},"references":{"type":"array","items":{"$ref":"#/components/schemas/Reference"},"maxItems":8,"default":[],"description":"Up to eight images from your library for the model to work from. **Input and output share a 9 megapixel budget** — at a 1 MP output that is eight references, at 2 MP it is seven — so send a smaller `variant` when you need more of them. Over budget is a 400 naming the numbers, never a silent drop. **Each reference is charged** at the output's per-megapixel rate, on the megapixels of the copy sent, with no minimum."},"folder_id":{"type":["string","null"],"description":"`fld_…` — the folder in your asset library the finished file is filed under. Omit it for the root. A folder that is not yours is a 400, never a silent fall back to the root.","examples":["fld_a1B2c3D4e5F6g7H8"]}},"required":["prompt"],"additionalProperties":false},"Reference":{"type":"object","properties":{"asset_id":{"type":"string","description":"`ast_…` — an image in your library.","examples":["ast_a1B2c3D4e5F6g7H8"]},"variant":{"type":"string","default":"original","description":"Which copy to send: `original`, or one of `50`, `25`, `12.5` — the smaller versions made when the image was stored. Smaller copies spend less of the 9 megapixel budget shared with the output, and cost less: a reference is charged on the copy sent. A variant that does not exist falls back to the original, which may put the request over budget."}},"required":["asset_id"],"additionalProperties":false},"VideoRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":4000,"description":"What should happen in the clip."},"aspect_ratio":{"type":"string","default":"16:9","description":"One of: 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16. Note this is **not** the same set images accept — video adds `2:1`."},"duration":{"type":"integer","minimum":5,"maximum":20,"default":5,"description":"Whole seconds. **This is what you are charged on** — the price is per second at a rate that depends on `resolution`."},"resolution":{"type":"string","default":"hd","description":"One of: hd, fhd. `hd` is 720p and `fhd` is 1080p, and they are **priced differently per second**."},"generate_audio":{"type":"boolean","default":true},"safety_tolerance":{"type":"integer","minimum":0,"maximum":4,"default":2,"description":"0 is strictest. **The ceiling is 4 here, not the 5 images allow.**"},"start_frame":{"type":["string","null"],"description":"`ast_…` — an image in your library to open the clip on. Omit for text-to-video."},"end_frame":{"type":["string","null"],"description":"`ast_…` — an image to close the clip on, pinned at `duration`. **Requires `start_frame`**."},"folder_id":{"type":["string","null"],"description":"`fld_…` — the folder in your asset library the finished file is filed under. Omit it for the root. A folder that is not yours is a 400, never a silent fall back to the root.","examples":["fld_a1B2c3D4e5F6g7H8"]}},"required":["prompt"],"additionalProperties":false},"AudioRequest":{"type":"object","properties":{"voice_id":{"type":"string","default":"default","description":"An id from `GET /v1/voices` — the built-in voice, a platform voice, or one your organisation uploaded."},"model":{"type":"string","default":"eleven_flash_v2_5","description":"Which model speaks: one of the voice's `models` in `GET /v1/voices` — `eleven_flash_v2_5` (the fastest, and the default), `eleven_multilingual_v2` or `eleven_v3`. A model the voice does not list is refused."},"provider_options":{"anyOf":[{"$ref":"#/components/schemas/ProviderVoiceSettings"},{"type":"null"}],"default":null,"description":"The provider's voice settings, on top of the ones the voice was registered with. Unset takes theirs."},"format":{"type":"string","enum":["wav","mp3","opus"],"default":"mp3","description":"One of: wav, mp3, opus."},"sample_rate":{"type":["integer","null"],"enum":[8000,16000,22050,24000,44100,null],"description":"Hz of the returned audio — one of 8000, 16000, 22050, 24000, 44100, each served natively by the provider. Unset means 24000.\n\n`POST /v1/tts` says what it produced in the `X-Sample-Rate` header. Queued speech (`POST /v1/audio`) does not take it: each of its formats has its own rate."},"text":{"type":"string","minLength":1,"maxLength":5000,"description":"What to say.","examples":["Oh wow, I was not expecting that at all!"]},"folder_id":{"type":["string","null"],"description":"`fld_…` — the folder in your asset library the finished file is filed under. Omit it for the root. A folder that is not yours is a 400, never a silent fall back to the root.","examples":["fld_a1B2c3D4e5F6g7H8"]}},"required":["text"],"additionalProperties":false},"ProviderVoiceSettings":{"type":"object","properties":{"stability":{"type":["number","null"],"minimum":0,"maximum":1,"default":null,"description":"Low is more expressive and less consistent between generations; high is flatter and more repeatable."},"similarity_boost":{"type":["number","null"],"minimum":0,"maximum":1,"default":null,"description":"How closely to cling to the original voice. High can reproduce artefacts in the source."},"style":{"type":["number","null"],"minimum":0,"maximum":1,"default":null,"description":"Style exaggeration. Costs latency; leave unset on anything conversational."},"use_speaker_boost":{"type":["boolean","null"],"default":null,"description":"Similarity at the cost of latency."},"speed":{"type":["number","null"],"minimum":0.7,"maximum":1.2,"default":null,"description":"1.0 is the voice's own pace."}},"additionalProperties":false},"SkyboxRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":550,"description":"The environment to build. Describe the whole surrounding — sky, ground, horizon and light — rather than a subject.","examples":["A salt flat at blue hour, thin cloud, distant mesas"]},"negative_text":{"type":["string","null"],"maxLength":200,"description":"What to keep out of it."},"style_id":{"type":["integer","null"],"minimum":1,"description":"One of the provider's styles — fetch the current list from `GET /v1/skybox/styles`. Omit for their default."},"seed":{"type":["integer","null"],"minimum":1,"maximum":2147483647,"description":"Reuse a seed to get the same environment again. **Note this starts at 1, not 0** — the provider uses zero for random."},"enhance_prompt":{"type":"boolean","default":false},"init_image":{"type":["string","null"],"description":"`ast_…` — an existing **equirectangular** image in your library to build from.","examples":["ast_a1B2c3D4e5F6g7H8"]},"init_strength":{"type":"number","minimum":0,"maximum":0.97,"default":0.5,"description":"How much the init image influences the result: 0 ignores it, 0.97 is the provider's maximum. Only has an effect alongside `init_image`."},"folder_id":{"type":["string","null"],"description":"`fld_…` — the folder in your asset library the finished file is filed under. Omit it for the root. A folder that is not yours is a 400, never a silent fall back to the root.","examples":["fld_a1B2c3D4e5F6g7H8"]}},"required":["prompt"],"additionalProperties":false},"GenerationPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationInfo"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"TranscribeAssetRequest":{"type":"object","properties":{"asset_id":{"type":"string","minLength":3,"maxLength":32,"description":"`ast_…`, from your asset library. Must be audio.","examples":["ast_a1B2c3D4e5F6g7H8"]},"model":{"type":"string","enum":["scribe_v2"],"default":"scribe_v2","description":"One of: scribe_v2."},"language":{"type":["string","null"],"default":null,"description":"ISO-639-1 or -639-3 code. Omit it and the language is detected automatically. Set it when you already know -- detection is very good and not free of mistakes, and a wrong guess costs the whole transcript.\n\n**`language_code` on the response is not this value.** It is ISO-639-3 whichever you sent, so `en` here comes back as `eng`.","examples":["en","fa","de"]},"diarize":{"type":"boolean","default":false,"description":"Label who is speaking. Each word gains a `speaker_id`. Adds processing time and is not free of error on overlapping speech."},"num_speakers":{"type":["integer","null"],"minimum":1,"maximum":32,"default":null,"description":"The most speakers to look for, when `diarize` is on. Ignored otherwise. Setting it when you know the number improves the labelling; leaving it out lets the provider decide."},"tag_audio_events":{"type":"boolean","default":false,"description":"Mark laughter, applause and similar in the transcript, as `(laughter)`-style entries with `type: audio_event`."},"timestamps":{"type":"boolean","default":false,"description":"Return each word with its `start_seconds` and `end_seconds`. Off by default because the array is far larger than the text -- an hour of speech is roughly ten thousand entries -- and most callers want the text."},"folder_id":{"type":["string","null"],"description":"`fld_…` — the folder in your asset library the finished file is filed under. Omit it for the root. A folder that is not yours is a 400, never a silent fall back to the root.","examples":["fld_a1B2c3D4e5F6g7H8"]}},"required":["asset_id"],"additionalProperties":false},"TemplatePage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateInfo"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"TemplateInfo":{"type":"object","properties":{"id":{"type":"string","description":"`tpl_…`.","examples":["tpl_a1B2c3D4e5F6g7H8"]},"name":{"type":"string"},"description":{"type":["string","null"]},"capability":{"type":"string","enum":["image","video","skybox"],"description":"What it generates, and so which scope the key needs to generate from it and which endpoint the result is polled on."},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/TemplateInput"},"description":"What to supply, in the order they are drawn."},"example_url":{"type":["string","null"],"description":"What it produces: a real output, generated by the platform from the example inputs shown beside each slot."},"credits_micros":{"type":["integer","null"],"description":"What one generation from it costs your organisation, in micro-credits (1 credit is 1,000,000). Knowable up front because every parameter is frozen — but on an image template your own pictures are charged on top, each at the output's per-megapixel rate and the size sent. Null when the platform has no rate for the capability.","examples":[2500000]},"fixed_megapixels":{"type":"number","description":"On an image template, the megapixels of the pictures the template itself sends with every generation, each charged at the output's per-megapixel rate and already in `credits_micros` — so an estimate that moves the output's size keeps this term as it is, and adds your own pictures at the size they are sent. 0 on a video or skybox template, whose price no picture changes.","examples":[2]},"parameters":{"type":"object","additionalProperties":{},"description":"The request the template froze, minus the prompt. Every entry is decided for you unless its name is in `exposed`, in which case it is the default you may override."},"exposed":{"type":"array","items":{"type":"string"},"description":"The parameters you may change, by name — pass a new value in `parameters` when generating. A change to a size, a duration or a resolution changes the price from the one quoted here.","examples":[["aspect_ratio","megapixels"]]},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"updated_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]}},"required":["id","name","description","capability","inputs","example_url","credits_micros","fixed_megapixels","parameters","exposed","created_at","updated_at"]},"TemplateGenerateRequest":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"type":"string"},"default":{},"description":"Slot name to value, one entry per input you are filling: an `ast_…` asset id for an `image` input, your text for a `text` one. Every `required` input must be present; an input the template does not open is a 422.","examples":[{"reference_1":"ast_a1B2c3D4e5F6g7H8"},{"prompt":"A red bicycle leaning on a brick wall"}]},"parameters":{"type":"object","additionalProperties":{},"default":{},"description":"Overrides for the parameters the template lists in `exposed`, by name, as `POST /v1/images` (or the capability's own route) would take them. A parameter the template did not expose is a 422 before anything is charged; a value the capability refuses is the same 422 that route would give.","examples":[{"megapixels":2,"aspect_ratio":"16:9"}]},"folder_id":{"type":["string","null"],"description":"`fld_…` — the folder in your asset library the finished file is filed under. Omit it for the root. A folder that is not yours is a 400, never a silent fall back to the root.","examples":["fld_a1B2c3D4e5F6g7H8"]}},"additionalProperties":false},"AssetPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AssetSummary"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"AssetSummary":{"type":"object","properties":{"id":{"type":"string","description":"`ast_…`"},"name":{"type":"string"},"kind":{"type":"string","enum":["input","output"],"description":"`input` if you uploaded it, `output` if a service made it"},"media_type":{"type":"string","enum":["audio","image","video","data"],"description":"What to do with the bytes — coarser than `content_type`, and what the library filters on. `data` is a lip-sync control track"},"content_type":{"type":"string","description":"The MIME type","examples":["image/jpeg"]},"size_bytes":{"type":"integer","description":"Size of the stored object"},"duration_seconds":{"type":["number","null"],"description":"How long the audio or video runs; null for a still"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"peaks":{"type":["array","null"],"items":{"type":"integer"},"description":"Waveform magnitudes, 0-100, for a mirrored strip. Empty means silent or unreadable; null means never computed."},"folder_id":{"type":["string","null"],"description":"`fld_…`, or null at the library root"},"capability":{"type":["string","null"],"enum":["tts","image","video","stt","skybox",null],"description":"Which capability produced it. Null for an upload","examples":["image"]},"origin":{"type":["string","null"],"enum":["api","console","end_user","platform",null],"description":"Which door it came through. Null for older rows"},"thumbnail_url":{"type":["string","null"],"description":"A short-lived link to a 512px square preview, for visual media only. Null for audio, for anything not yet converted, and for anything stored before previews existed."},"status":{"type":"string","enum":["pending","ready","failed"],"description":"`pending` while an upload converts, then `ready` or `failed`. Everything a service produces is `ready` immediately."},"error":{"type":["string","null"],"description":"Why an upload could not be converted. Null otherwise."},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]}},"required":["id","name","kind","media_type","content_type","size_bytes","duration_seconds","width","height","peaks","folder_id","capability","origin","thumbnail_url","status","error","created_at"]},"UploadTicket":{"type":"object","properties":{"asset_id":{"type":"string","description":"Pass this back to confirm the upload.","examples":["ast_a1B2c3D4e5F6g7H8"]},"url":{"type":"string","description":"PUT the file here, unmodified, with the `Content-Type` you asked for and no authentication headers — the URL carries its own. It expires; ask for another if it does."},"expires_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"],"description":"When `url` stops accepting the upload."}},"required":["asset_id","url","expires_at"]},"UploadTicketRequest":{"type":"object","properties":{"content_type":{"type":"string","description":"What you are about to upload. Signed into the URL, so the upload must send exactly this `Content-Type`, and checked against the stored object when you confirm.","examples":["image/png"]}},"required":["content_type"],"additionalProperties":false},"AssetDetail":{"type":"object","properties":{"id":{"type":"string","description":"`ast_…`"},"name":{"type":"string"},"kind":{"type":"string","enum":["input","output"],"description":"`input` if you uploaded it, `output` if a service made it"},"media_type":{"type":"string","enum":["audio","image","video","data"],"description":"What to do with the bytes — coarser than `content_type`, and what the library filters on. `data` is a lip-sync control track"},"content_type":{"type":"string","description":"The MIME type","examples":["image/jpeg"]},"size_bytes":{"type":"integer","description":"Size of the stored object"},"duration_seconds":{"type":["number","null"],"description":"How long the audio or video runs; null for a still"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"peaks":{"type":["array","null"],"items":{"type":"integer"},"description":"Waveform magnitudes, 0-100, for a mirrored strip. Empty means silent or unreadable; null means never computed."},"folder_id":{"type":["string","null"],"description":"`fld_…`, or null at the library root"},"capability":{"type":["string","null"],"enum":["tts","image","video","stt","skybox",null],"description":"Which capability produced it. Null for an upload","examples":["image"]},"origin":{"type":["string","null"],"enum":["api","console","end_user","platform",null],"description":"Which door it came through. Null for older rows"},"thumbnail_url":{"type":["string","null"],"description":"A short-lived link to a 512px square preview, for visual media only. Null for audio, for anything not yet converted, and for anything stored before previews existed."},"status":{"type":"string","enum":["pending","ready","failed"],"description":"`pending` while an upload converts, then `ready` or `failed`. Everything a service produces is `ready` immediately."},"error":{"type":["string","null"],"description":"Why an upload could not be converted. Null otherwise."},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"request_id":{"type":["string","null"],"description":"`req_…` — the call that produced this"},"end_user_id":{"type":["string","null"]},"meta":{"type":["object","null"],"additionalProperties":{}},"url":{"type":["string","null"],"description":"Time-limited link to the bytes. Null when object storage is unavailable."},"url_expires_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"],"description":"When `url`, the variants' links and `preview_url` stop working; null when there is no `url`. Fetch the asset again for fresh ones."},"preview_url":{"type":["string","null"],"description":"A displayable copy, when `url` is not displayable. Set for skyboxes, whose `url` is a Radiance `.hdr`; null otherwise."},"variants":{"type":"array","items":{"$ref":"#/components/schemas/VariantInfo"},"description":"Smaller copies of the same image, largest first. Empty for audio and for anything that has none."}},"required":["id","name","kind","media_type","content_type","size_bytes","duration_seconds","width","height","peaks","folder_id","capability","origin","thumbnail_url","status","error","created_at","request_id","end_user_id","meta","url","url_expires_at","preview_url","variants"]},"VariantInfo":{"type":"object","properties":{"name":{"type":"string","description":"`50`, `25` or `12.5` — the percentage of the original"},"width":{"type":"integer"},"height":{"type":"integer"},"size_bytes":{"type":"integer"},"url":{"type":["string","null"],"description":"Time-limited link to this copy, good until the asset's `url_expires_at`."}},"required":["name","width","height","size_bytes","url"]},"UploadConfirm":{"type":"object","properties":{"asset_id":{"type":"string","description":"From the ticket.","examples":["ast_a1B2c3D4e5F6g7H8"]},"content_type":{"type":"string","description":"What was uploaded.","examples":["image/png"]},"filename":{"type":"string","description":"The file's own name; the asset is called this, less its extension, when `name` is not given."},"name":{"type":"string","description":"What to call the asset."},"folder_id":{"type":["string","null"],"description":"`fld_…` — the folder to file it in; omit it, or `null`, for the root. A folder that is not yours is a 404."}},"required":["asset_id","content_type"],"additionalProperties":false},"AssetsAffected":{"type":"object","properties":{"affected":{"type":"integer"}},"required":["affected"]},"AssetBulkRequest":{"type":"object","properties":{"asset_ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500}},"required":["asset_ids"],"additionalProperties":false},"AssetMoveRequest":{"type":"object","properties":{"asset_ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500},"folder_id":{"type":["string","null"],"description":"`fld_…`, or null for the root"}},"required":["asset_ids","folder_id"],"additionalProperties":false},"AssetUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"folder_id":{"type":["string","null"],"description":"`fld_…`, or null for the root; omit it to leave it"}},"additionalProperties":false},"FolderPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FolderSummary"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"FolderSummary":{"type":"object","properties":{"id":{"type":"string","description":"`fld_…`"},"name":{"type":"string"},"parent_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"asset_count":{"type":["integer","null"],"description":"Live assets directly in this folder"},"folder_count":{"type":["integer","null"],"description":"Subfolders directly in this folder"}},"required":["id","name","parent_id","created_at","asset_count","folder_count"]},"FolderDetail":{"type":"object","properties":{"id":{"type":"string","description":"`fld_…`"},"name":{"type":"string"},"parent_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"asset_count":{"type":["integer","null"],"description":"Live assets directly in this folder"},"folder_count":{"type":["integer","null"],"description":"Subfolders directly in this folder"},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/FolderSummary"},"description":"The folders above it, top level first"}},"required":["id","name","parent_id","created_at","asset_count","folder_count","ancestors"]},"FolderCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"parent_id":{"type":["string","null"],"description":"`fld_…`; omit it, or `null`, for the top level"}},"required":["name"],"additionalProperties":false},"FolderUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"parent_id":{"type":["string","null"],"description":"`fld_…`, or null for the top level; omit it to leave it"}},"additionalProperties":false},"FolderDeleted":{"type":"object","properties":{"moved_assets":{"type":"integer","description":"Assets that moved up to the parent rather than being deleted"},"moved_folders":{"type":"integer","description":"Subfolders that moved up to the parent"}},"required":["moved_assets","moved_folders"]},"SessionDetail":{"type":"object","properties":{"agent_id":{"type":"string"},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"end_user_id":{"type":"string","description":"Who this conversation is with. Send it again to open another conversation with the same person, carrying their memory.","examples":["eu_7Kq2mZp1XvA9dRt4"]},"id":{"type":"string"},"title":{"type":["string","null"]},"turn_seq":{"type":"integer"},"updated_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"messages":{"$ref":"#/components/schemas/MessagePage"},"relation":{"anyOf":[{"$ref":"#/components/schemas/RelationInfo"},{"type":"null"}],"description":"How this agent stands with this person, as the conversation opens.\n\n**Null when the agent has `relation_enabled` off**, which is not the same as \"they have no history\": the counters run for every pair regardless, and returning one for an agent that keeps none would show a relationship the model is not being told about.\n\nIt belongs to the **person**, not the conversation, so it carries across every session with the same `end_user_id`. Here so that rendering it at conversation start needs no second call; `GET /v1/agent/relations` is still how you read it any other time, and the socket's `relation` event is how you learn it moved mid-turn — which is rare, and is the only time it changes."},"resumed":{"type":"boolean","description":"True when this is a conversation that already existed rather than a new one — see `resume` on the request.\n\nWorth branching on: a resumed session arrives with its `messages` already populated and its `turn_seq` past zero, so a client that assumed an empty transcript will render nothing until the next turn."}},"required":["agent_id","created_at","end_user_id","id","title","turn_seq","updated_at","messages","relation","resumed"],"description":"A conversation, and a page of it. `messages` is the conversation so far, oldest first.\n\n**The most recent 50 by default**, not the whole transcript — a long conversation is not something a caller can be handed in one response. `messages.next_cursor` reaches the older ones: pass it as `cursor` on `GET /v1/agent/sessions/{session_id}`, whose `limit` raises or lowers the page, up to 200. It is null once the page reaches the beginning of the conversation.\n\n**`messages` is empty on a new conversation, including for an agent that has an opening line**. The opening line — generated or scripted — is the first turn on `/v1/agent/stream`, so it is written when a client connects rather than when the session is created. Opening a session makes no model call and no speech call of any kind."},"MessagePage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MessageInfo"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"MessageInfo":{"type":"object","properties":{"content":{"type":"string"},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"id":{"type":"string"},"knowledge":{"anyOf":[{"$ref":"#/components/schemas/MessageKnowledge"},{"type":"null"}],"description":"On a reply: what the agent looked up in its knowledge for it — each lookup's query, outcome and the entries it found, with their scores. Null when nothing was looked up."},"mood":{"type":["string","null"],"description":"How the agent said it felt when it wrote this reply, when the agent reports moods. Null on user messages, on agents with emotion off, and on any reply where the model did not report a usable one.","examples":["happy"]},"mood_intensity":{"type":["number","null"],"description":"How strongly, 0 to 1. Null when the model gave a label without a number — the label is the half it gets right."},"role":{"type":"string","enum":["user","assistant"],"examples":["assistant"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/MessageSource"},"description":"On a reply: the web pages it read, with the agent's `url_context` switch on. Empty when it read none, and on the person's messages."},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/MessageToolCall"},"description":"On a reply: the calls of your tools it made, in order, each with its arguments and what it answered. Empty when it called none, and on the person's messages."}},"required":["content","created_at","id","knowledge","mood","mood_intensity","role","sources","tool_calls"]},"MessageKnowledge":{"type":"object","properties":{"lookups":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeLookupInfo"}},"mode":{"type":"string","enum":["lookup","prompt"],"description":"How the agent read its knowledge on this turn: `lookup` or `prompt`.","examples":["lookup"]}},"required":["lookups","mode"]},"KnowledgeLookupInfo":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeCitation"}},"outcome":{"type":"string","enum":["found","none","failed"],"description":"`found`, `none` (nothing relevant enough), or `failed` (the lookup itself could not be done).","examples":["found"]},"query":{"type":"string"},"via":{"type":"string","enum":["first","tool"],"description":"`first` — looked up before the reply; `tool` — the model asked for it.","examples":["first"]}},"required":["hits","outcome","query","via"]},"KnowledgeCitation":{"type":"object","properties":{"entry_id":{"type":"string"},"score":{"type":"number"},"title":{"type":"string"}},"required":["entry_id","score","title"]},"MessageSource":{"type":"object","properties":{"url":{"type":"string","examples":["https://shop.example.com/returns"]},"retrieved":{"type":"boolean","description":"Whether the page could be read. A reply may name a page it could not fetch — behind a login, refused by its site, gone — and answers without it."}},"required":["url","retrieved"],"description":"A web page the reply read with the agent's `url_context` switch on."},"MessageToolCall":{"type":"object","properties":{"call_id":{"type":"string","description":"The call's id, `call_…`: what your server or app was sent."},"name":{"type":"string"},"kind":{"type":"string","enum":["webhook","app"]},"arguments":{"type":"object","additionalProperties":{},"description":"What the model called it with."},"result":{"description":"What it answered, as the model read it — its JSON, or its text, cut at the platform's `agents.tools.result_max_bytes` (`GET /v1/platform/limits`). Null when it answered nothing."},"ok":{"type":"boolean","description":"It answered in time, with a 2xx or a result."},"error":{"type":["string","null"],"description":"What failed, as the model was told — or, for a tool that asks first, that it waited for the person's yes. Null when nothing did."},"ms":{"type":"integer","description":"How long it took."},"round":{"type":"integer","description":"Which of the reply's rounds of calls, 1 to 3; 0 for a call the person confirmed with a tap."}},"required":["call_id","name","kind","arguments","ok","error","ms","round"]},"RelationInfo":{"type":"object","properties":{"agent_id":{"type":"string"},"agent_name":{"type":["string","null"],"description":"The agent's name, so a list of these is readable without resolving ids.","examples":["Aria"]},"conversations":{"type":"integer","description":"Separate sessions, ever. A stronger signal of familiarity than `turns` — twenty short visits is a longer acquaintance than one long conversation."},"disclosure":{"type":"number","description":"How much the agent has told **them** about itself, -1 to 1 — the asymmetric half of knowing each other, and the one nothing can count.\n\nDeliberately not part of `tier`: an agent can have opened up to somebody it has come to dislike, and folding this into affection would make that state unrepresentable."},"end_user_id":{"type":"string","description":"The person, as `eu_...`.","examples":["eu_7Fk2mQ9xLp4Rv1Nt"]},"first_met_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"last_seen_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"note":{"type":["string","null"],"description":"One line the model wrote about them. **Replaced, not appended** — it is rendered into every future prompt for this pair, so it is bounded by design."},"recorded":{"type":"integer","description":"How many times the model has recorded a change. Zero on a long history means the tool is not being called, which is the first thing to check when a relationship is not moving."},"summary":{"type":"string","description":"The relationship as the model is told it — bands and counted phrases, never numbers. **Empty string** when there is nothing worth saying yet, in which case nothing about them is added to the prompt at all — which is a real state and not a missing value."},"tier":{"type":"string","enum":["Despised","Disliked","Acquaintances","Friends","Good Friends"],"description":"What the agent would call this relationship, and what it is actually told: **Despised, Disliked, Acquaintances, Friends** or **Good Friends**.\n\nDerived on every read from the axes below and never stored, so it cannot go stale. The rule is one sentence: *warmth and trust set the direction, familiarity sets how far it can go* — a first conversation caps at Acquaintances however well it went, and the ceiling rises as they talk. Dislike is not capped: an agent can take against somebody on one remark.","examples":["Friends"]},"trust":{"type":"number","description":"-1 to 1, on the same scale."},"turns":{"type":"integer","description":"Turns exchanged, ever. Counted, not judged."},"warmth":{"type":"number","description":"-1 to 1. Zero is indifference, which is where every relationship starts."}},"required":["agent_id","agent_name","conversations","disclosure","end_user_id","first_met_at","last_seen_at","note","recorded","summary","tier","trust","turns","warmth"]},"SessionCreateRequest":{"type":"object","properties":{"agent_id":{"type":"string","description":"Which agent this conversation is with."},"end_user_id":{"type":["string","null"],"maxLength":128,"description":"Optional, and only ever the key's own end user — their id from `POST /v1/end-users`, or your own id for them.\n\n**A conversation is always the person the ephemeral key was minted for**: the key says who is talking, so this can only confirm it, and naming anybody else is a **403**. What the agent remembers about them — durable facts and the standing relationship — is theirs, and carries into every conversation with any of your agents.\n\nSet once, when the session opens. It cannot change afterwards.","examples":["eu_7Kq2mZp1XvA9dRt4"]},"resume":{"type":["boolean","null"],"description":"Whether to continue this person's most recent conversation with this agent instead of starting a new one.\n\n**Unset is the useful default**: it resumes when this person has a conversation with this agent young enough to continue — within the organisation's `resume_max_age_days`, else the platform's `agents.sessions.resume_max_age_days` (`GET /v1/platform/limits`) — and starts a new one otherwise. That matches what 'open a conversation with this person' usually means, and it stops an integration that opens a session per page load from scattering somebody's history across a dozen fragments.\n\n`false` always starts a new conversation — this is what a 'new chat' button should send. `true` is the same as leaving it unset; it exists so the intent can be stated rather than implied.\n\nNothing is lost by starting fresh: durable facts and the standing relationship belong to the *person*, not the conversation, and are carried into every new one.\n\nThe response's `resumed` says which happened."},"title":{"type":["string","null"],"maxLength":255,"description":"Optional label."}},"required":["agent_id"],"additionalProperties":false},"SessionPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionInfo"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"SessionInfo":{"type":"object","properties":{"agent_id":{"type":"string"},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"end_user_id":{"type":"string","description":"Who this conversation is with. Send it again to open another conversation with the same person, carrying their memory.","examples":["eu_7Kq2mZp1XvA9dRt4"]},"id":{"type":"string"},"title":{"type":["string","null"]},"turn_seq":{"type":"integer"},"updated_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]}},"required":["agent_id","created_at","end_user_id","id","title","turn_seq","updated_at"]},"CompactionInfo":{"type":"object","properties":{"after_seq":{"type":"integer","description":"The last message this summary covers. Anything after it — the last few exchanges, kept word for word, then whatever is said next — is still sent to the model verbatim."},"facts_stored":{"type":"integer","description":"Durable facts written to long-term memory by this call. Zero when extraction was not asked for, or when there was nothing worth keeping."},"input_tokens":{"type":["integer","null"]},"model":{"type":["string","null"],"description":"What produced the summary."},"output_tokens":{"type":["integer","null"]},"session_id":{"type":"string"},"summary":{"type":"string","description":"What the next turn will start from."},"trigger":{"type":"string","enum":["manual","automatic","idle"],"description":"`manual` (a client asked) or `automatic` (a turn reached the agent's threshold, or a long compaction's next pass). `idle` is no longer written: it marks compactions made when a quiet conversation's facts were read, before facts were read on their own.","examples":["manual"]}},"required":["after_seq","facts_stored","input_tokens","model","output_tokens","session_id","summary","trigger"]},"CompactRequest":{"type":"object","properties":{"extract_facts":{"type":["boolean","null"],"description":"Whether to also extract durable facts about the end user, in the same model call.\n\nUnset uses the agent's own setting."}},"additionalProperties":false},"FactPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FactInfo"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"FactInfo":{"type":"object","properties":{"agent_id":{"type":["string","null"],"description":"Which agent was being talked to when this was learned."},"confirmed_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"],"description":"When a conversation last said it again; `null` for never. The agents see the most recently confirmed first when not every fact fits."},"created_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"]},"id":{"type":"string"},"replaced_at":{"type":["string","null"],"format":"date-time","examples":["2026-10-24T09:30:00.000Z"],"description":"When a later conversation replaced or removed it; `null` while it stands. Listed only with `include_replaced=true`."},"replaced_by":{"type":["string","null"],"description":"The fact that replaced it — moved city, changed job — or `null` when it was removed with nothing in its place, or stands."},"scope":{"type":"string","enum":["person","agent"],"description":"`person`: recalled by every agent of yours that shares its facts. `agent`: kept to one agent (`agent_id`), which alone recalls it — learnt by an agent whose `facts_scope` is `agent`, or added for that agent."},"source":{"type":"string","enum":["conversation","customer"],"description":"`conversation`: a reading learnt it. `customer`: you added or corrected it — a later conversation never replaces or removes it."},"text":{"type":"string"},"updated_at":{"type":"string","format":"date-time","examples":["2026-10-24T09:30:00.000Z"],"description":"When it last changed: its `replaced_at` once replaced, else when you last corrected it, else its `created_at`."}},"required":["agent_id","confirmed_at","created_at","id","replaced_at","replaced_by","scope","source","text","updated_at"]},"FactCreateRequest":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500,"description":"What to remember about the person, as one plain statement: \"Prefers to be called Sam.\" At most 500 characters. Never a secret — a password, a code, a card, account or identity number, or a key is refused, since facts are sent to the model on every turn.","examples":["Prefers to be called Sam."]},"agent_id":{"type":["string","null"],"description":"Keep it to one agent: only that agent recalls it. Unset or `null`: every agent of yours that shares its facts — and the ones that keep their own, too."}},"required":["text"],"additionalProperties":false},"FactUpdateRequest":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500,"description":"What to remember about the person, as one plain statement: \"Prefers to be called Sam.\" At most 500 characters. Never a secret — a password, a code, a card, account or identity number, or a key is refused, since facts are sent to the model on every turn.","examples":["Prefers to be called Sam."]}},"required":["text"],"additionalProperties":false},"FactsDeleted":{"type":"object","properties":{"facts_deleted":{"type":"integer","description":"How many stored facts were deleted."}},"required":["facts_deleted"]},"RelationPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RelationInfo"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"AgentPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentSummary"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; `null` when this is the last."}},"required":["data","next_cursor"]},"AgentSummary":{"type":"object","properties":{"code_execution":{"type":"boolean","description":"Whether the model may write and run Python while it replies — sums, unit conversions, dates — and answer from what it printed. Gemini's own tool: it runs at Google, with no network, and nothing of yours.\n\n**No fee, but not free**: the code and its output are model tokens, billed like any reply."},"compact_instruction":{"type":["string","null"],"maxLength":4000,"description":"What to tell the model when summarising. Unset uses the organisation's default, then a built-in instruction written for in-character conversations."},"compact_max_output_tokens":{"type":["integer","null"],"minimum":1,"maximum":65536,"description":"Length cap on the summary, in tokens — the model's thinking included, which shares the budget. Unset uses the platform's `agents.memory.compaction.max_output_tokens` on the Limits page, twice it when the compaction extracts facts too."},"compact_model":{"type":["string","null"],"maxLength":64,"description":"Model for the summarising call. Unset uses the agent's own."},"compact_thinking_level":{"type":["string","null"],"enum":["minimal","low","medium","high",null],"description":"Thinking level for the summarising call."},"compact_threshold_tokens":{"type":["integer","null"],"minimum":1,"maximum":200000,"description":"Compact automatically once a reply's first model call reads this many tokens — the conversation, its summary and the instruction, without the inline knowledge or the turn's looked-up passages, which no summary shrinks. Tool results do not count. Unset uses the platform's default, `agents.memory.compaction.default_threshold_tokens` on the Limits page. At most 200,000, and at least twice what the instruction costs on its own. `POST /v1/agent/sessions/{id}/compact` works whatever it is."},"emotion_enabled":{"type":"boolean","description":"Whether the model reports its own mood — one line in front of each reply, which is taken off the reply and sent as the socket's `mood` event, and kept on each stored message.\n\nCosts about six output tokens per turn and no extra model call. The reply text you are handed does not contain the line: a marker with a known label, or with an intensity, or alone on its own line is always removed, and only a marker with an unknown label, no intensity and prose on the same line is left — at that point it cannot be told from a sentence that happens to start with the word."},"emotion_instruction":{"type":["string","null"],"maxLength":4000,"description":"What the model is told about reporting a mood. Unset uses the organisation's default, then a built-in one naming every supported label.\n\n**Override this and you own the format.** The gateway strips a first line shaped `mood: