{ "openapi": "3.1.0", "info": { "title": "Realtime Avatar API", "version": "1.0.0", "summary": "Put a live, talking AI character into your product on a voice or video call.", "description": "Create an avatar from a single portrait, mint a session from your own server, and stream that character's voice and face in realtime while your own tools run inside the conversation. Full-duplex: the caller can interrupt, and end-of-turn is judged by what was said rather than by silence. Billed by the second — one credit is one second on air, with the language model, the voice and the rendering all included in that rate. Delivery is over LiveKit WebRTC; the browser and native halves are the `realtime-avatar` TypeScript SDK on npm. Agent-readable companions: https://realtimeavatar.ai/llms.txt (index), https://realtimeavatar.ai/llms-full.txt (every doc page inline), https://realtimeavatar.ai/pricing.md (rates).", "termsOfService": "https://realtimeavatar.ai/terms", "contact": { "name": "Realtime Avatar support", "url": "https://realtimeavatar.ai/docs" }, "license": { "name": "Proprietary — see terms of service", "url": "https://realtimeavatar.ai/terms" } }, "servers": [ { "url": "https://realtimeavatar.ai/api", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key, sent as `Authorization: Bearer `. Keys carry named scopes; each operation declares the one it needs in `x-required-scopes`, and the catalogue of all of them is `x-scopes` on this scheme. A 401 or 403 from this API answers with a `WWW-Authenticate` challenge whose `resource_metadata` points at https://realtimeavatar.ai/.well-known/oauth-protected-resource/api (RFC 9728), which repeats the scope list machine-readably. Mint a key in the dashboard or with `POST /v1/api-keys`.", "x-scopes": { "avatars:read": "List and read avatars, their clips and their assets.", "avatars:write": "Create, update and delete avatars; upload assets; change clips and the resting loop.", "realtime:write": "Mint and release live calls, and read pool capacity.", "credits:read": "Read the workspace credit balance and what live calls are holding.", "usage:read": "Read per-session billed usage detail.", "recordings:read": "Read private recording metadata and issue playback URLs.", "usage:write": "Report usage events. Reserved for first-party runtimes; no public operation requires it.", "api_keys:write": "Mint further API keys.", "*": "Every operation. Granted by the dashboard's default key for convenience — prefer the narrow scopes above, which are what an agent should request." } } }, "schemas": { "LiveKitSessionRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "avatar_id": { "type": "string", "minLength": 1, "maxLength": 160 }, "background_id": { "default": "plain_white", "type": "string", "minLength": 1, "maxLength": 160 }, "capacity_pool": { "default": "primary", "type": "string", "minLength": 1, "maxLength": 80 }, "mode": { "default": "avatar", "type": "string", "enum": [ "avatar", "voice" ] }, "create_room": { "default": true, "type": "boolean" }, "dispatch_agent": { "default": true, "type": "boolean" }, "instructions": { "type": "string", "minLength": 1, "maxLength": 16000 }, "initial_context": { "default": [], "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "role", "content" ], "additionalProperties": false } }, "initial_say": { "type": "string", "minLength": 1, "maxLength": 1000 }, "llm": { "anyOf": [ { "type": "object", "properties": { "backend": { "description": "Which model answers the turns. `external` is enabled per workspace for server-to-server callers and needs endpoint configuration that is not part of this document; a workspace without it is refused with 403.", "type": "string", "enum": [ "local", "gemini", "openai", "external" ] }, "model": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "max_session_seconds": { "type": "integer", "minimum": 1, "maximum": 1800 }, "participant_identity": { "type": "string", "minLength": 1, "maxLength": 160 }, "participant_name": { "type": "string", "maxLength": 160 }, "character_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "queue_ticket_id": { "type": "string", "minLength": 1, "maxLength": 160 }, "room_name": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Optional room label. RTA appends the session identity; use the returned grant's room name to connect. A new call never joins an existing session." }, "source_kind": { "default": "source_video", "description": "The realtime source. Creation is image-only — every avatar grows its own PLATFORM-GENERATED looping source video from the uploaded portrait — so this is always \"source_video\".", "type": "string", "enum": [ "source_video" ] }, "source_video_url": { "description": "Normally omitted: the avatar's platform-generated idle loop is resolved server-side. Overriding it with a custom video URL is a legacy channel for existing integrations — custom video is not part of the public contract.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "stt_mode": { "default": "server", "type": "string", "enum": [ "server", "off" ] }, "transcription": { "description": "Optional speech recognition hints. Omit language_codes or send [] for automatic multilingual detection. Custom vocabulary biases recognition; at most 100 relevant terms is recommended. It is not a character instruction or a guarantee of recognition accuracy or latency.", "type": "object", "properties": { "language_codes": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 64 } }, "custom_vocabulary": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "\\S" } } }, "additionalProperties": false }, "camera": { "type": "boolean" }, "video_cache_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 240 }, { "type": "null" } ] }, "voice": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "const": "cartesia" }, "model": { "default": "cartesia/sonic-3", "type": "string", "enum": [ "cartesia/sonic-2", "cartesia/sonic-2-latest", "cartesia/sonic-3", "cartesia/sonic-3-latest", "cartesia/sonic-turbo", "cartesia/sonic-turbo-latest" ] }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "speed": { "anyOf": [ { "type": "number", "minimum": 0.5, "maximum": 2 }, { "type": "null" } ] }, "emotion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 16 }, { "type": "null" } ] } }, "required": [ "provider", "voice_id" ], "additionalProperties": false }, { "type": "object", "properties": { "provider": { "type": "string", "const": "breezeblue" }, "model": { "default": "bluebell-v1-en", "type": "string", "minLength": 1, "maxLength": 80 }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "guidance_scale": { "anyOf": [ { "type": "number", "minimum": 1, "maximum": 10 }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1000 }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 16 }, { "type": "null" } ] } }, "required": [ "provider", "voice_id" ], "additionalProperties": false }, { "type": "object", "properties": { "provider": { "type": "string", "const": "fish" }, "model": { "default": "speech-1.6", "type": "string", "enum": [ "speech-1.6", "s1", "s2-pro", "drama-3", "speech-1.5", "s1-mini" ] }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "speed": { "anyOf": [ { "type": "number", "minimum": 0.5, "maximum": 2 }, { "type": "null" } ] }, "emotion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 16 }, { "type": "null" } ] } }, "required": [ "provider", "voice_id" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "voice_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 240 }, { "type": "null" } ] }, "clip_library": { "description": "The session's motion-state map. Normally omitted: the avatar's PLATFORM-GENERATED library (idle / listen / gesture clips rendered from the portrait at creation) is injected automatically. An explicit [] opts the call out of clips. Supplying custom clip URLs is a legacy channel for existing integrations — custom video is not part of the public contract.", "type": "array", "items": { "type": "object", "properties": { "clip_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "source_video_url": { "description": "The clip's video URL — for a platform-generated library this is the generated clip's hosted URL, filled in server-side at hydration.", "type": "string", "format": "uri" }, "video_cache_id": { "type": "string", "minLength": 8, "maxLength": 160 }, "max_seconds": { "type": "number", "minimum": 1, "maximum": 10 }, "trigger": { "type": "string", "enum": [ "idle", "listen", "think", "directive" ] }, "loop": { "type": "boolean" }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "crossfade_ms": { "type": "integer", "minimum": 0, "maximum": 1000 }, "trim_start_ms": { "type": "integer", "minimum": 0, "maximum": 2000 }, "trim_end_ms": { "type": "integer", "minimum": 0, "maximum": 2000 }, "when": { "type": "string", "minLength": 1, "maxLength": 120 }, "hint": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "clip_id" ], "additionalProperties": false } }, "clip_behavior": { "type": "object", "properties": { "idle": { "type": "object", "properties": { "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "weights": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } } }, "required": [ "clips" ], "additionalProperties": false }, "on": { "type": "object", "properties": { "userSpeechStarted": { "type": "object", "properties": { "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } }, "required": [ "clips" ], "additionalProperties": false } }, "additionalProperties": false }, "actions": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 512 }, "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } }, "required": [ "description", "clips" ], "additionalProperties": false } } }, "additionalProperties": false }, "choreography": { "type": "object", "properties": { "idle_dwell_min_seconds": { "type": "number", "minimum": 1, "maximum": 60 }, "idle_dwell_max_seconds": { "type": "number", "minimum": 1, "maximum": 120 }, "special_weight": { "type": "number", "minimum": 0, "maximum": 100 }, "start_grace_seconds": { "type": "number", "minimum": 0, "maximum": 60 }, "crossfade_ms": { "type": "integer", "minimum": 0, "maximum": 1000 }, "crossfade_easing": { "type": "string", "enum": [ "linear", "smooth", "ease_out" ] }, "wrap_crossfade_ms": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false }, "behavior": { "type": "object", "properties": { "gestures_enabled": { "type": "boolean" } }, "additionalProperties": false }, "expression_profile": { "type": "string", "minLength": 1, "maxLength": 40 }, "render_backend": { "type": "string", "enum": [ "warp", "generative" ] }, "support_edits": { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1000 }, "reference_url": { "type": "string", "format": "uri" }, "live_edit": { "description": "EXPERIMENTAL (\"runtime edit\") — let the look follow the conversation mid-call. Less settled than the fixed `instruction` lane: the shape may still change, and the re-dress does not reach every capacity tier yet, so a live session is accepted and runs normally but may hold its opening set for the whole call. Absent means `instruction` is fixed for the session, which is the incumbent behavior.", "type": "object", "properties": { "rules": { "type": "string", "minLength": 1, "maxLength": 2000 }, "cooldown_seconds": { "type": "integer", "minimum": 5, "maximum": 600 }, "renderer": { "type": "string", "enum": [ "editor", "generative" ] }, "objects": { "type": "string", "enum": [ "editor", "generative" ] } }, "required": [ "rules" ], "additionalProperties": false } }, "required": [ "instruction" ], "additionalProperties": false }, "transcript_webhook": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri" }, "secret": { "type": "string", "minLength": 16, "maxLength": 200 } }, "required": [ "url", "secret" ], "additionalProperties": false }, "content_policy": { "type": "string", "enum": [ "minor-sexual-content-v1", "safe-content-v1" ], "description": "Server-authored content enforcement policy. API-key integrators may request it; browser mints strip it. No default. Requires worker enforcement before emission; transport alone does not provide protection." }, "recording": { "type": "string", "enum": [ "off", "audio", "video", "audio_video", "participants", "tracks" ], "description": "Server-owned recording policy; omitted means off. Legacy audio includes user and avatar audio. participants saves one continuous audio/video file per participant, without mixing their voices. tracks saves each published participant audio/video track separately; list recordings by session after capture." }, "connection_history": { "type": "boolean" }, "client_metadata": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "maxProperties": 16 }, "fast_endpointing": { "description": "DEPRECATED, no-op. Accepted and ignored. The faster hesitation ceiling this requested is now the default for every session, so sending it changes nothing. Safe to stop sending; the field is retained only so existing callers do not break.", "type": "boolean" }, "require_ready_clip_library": { "type": "boolean" }, "scene": { "description": "Preview, enabled per workspace. A prepared scene from POST /v1/scenes, played forward over its full length in place of the avatar's source video; the avatar keeps the voice and persona. Cannot be combined with mode voice, render_backend generative, source_video_url, video_cache_id or a non-empty clip_library.", "type": "object", "properties": { "video_cache_id": { "type": "string", "pattern": "^rtav_[0-9a-f]{32}$", "description": "The prepared scene's artifact id, as returned by POST /v1/scenes when status is ready." }, "first_frames": { "description": "Frames in the first clip. The loop closes seamlessly at the wrap only when a continuation follows it.", "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "total_frames": { "description": "Frames in the whole artifact (first plus continuation).", "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 }, "attach_continuation": { "description": "Preview. Set when this scene is a first clip alone: the joined scene (the same first clip plus its continuation) that this workspace prepares after the mint may then be attached to the live call. Linking needs the first clip's md5 and bytes declared on both prepares. Absent or false plays this scene for the whole call.", "type": "boolean" } }, "required": [ "video_cache_id" ], "additionalProperties": false } }, "required": [ "avatar_id" ], "additionalProperties": false }, "LiveKitSessionGrant": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "usage_account_id": { "readOnly": true, "description": "Returned only for X-RTA-Observability: identity-v1 after successful platform billing attachment. The authoritative billing hold tenant ID; never client metadata or provider identity. Omitted by default and on failed or queued responses. Older servers may omit it.", "type": "string" }, "releaseIdentity": { "readOnly": true, "description": "Returned only for X-RTA-Release-Evidence: 1. Omitted by default for strict SDK compatibility. Missing deployment or worker evidence remains null.", "type": "object", "properties": { "deploymentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "workerRevision": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{40}$" }, { "type": "null" } ] }, "provenance": { "type": "object", "properties": { "deploymentSource": { "type": "string", "const": "cloudflare-worker-version" }, "workerSource": { "anyOf": [ { "type": "string", "const": "authenticated-worker-heartbeat" }, { "type": "null" } ] }, "workerId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "podStartedAtMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "workerObservedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "deploymentSource", "workerSource", "workerId", "podStartedAtMs", "workerObservedAt" ], "additionalProperties": false } }, "required": [ "deploymentId", "workerRevision", "provenance" ], "additionalProperties": false }, "status": { "default": "ready", "type": "string", "const": "ready" }, "session_id": { "type": "string", "minLength": 1 }, "room_name": { "type": "string", "minLength": 1 }, "livekit_url": { "type": "string", "minLength": 1 }, "participant_token": { "type": "string", "minLength": 1 }, "participant_identity": { "type": "string", "minLength": 1 }, "agent_name": { "type": "string", "minLength": 1 }, "capacity_pool": { "type": "string", "minLength": 1 }, "reservation_expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "max_sessions_per_gpu": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "stt_mode": { "default": "server", "type": "string", "enum": [ "server", "off" ] }, "camera": { "type": "boolean" }, "room_created": { "default": false, "type": "boolean" }, "dispatch_created": { "default": false, "type": "boolean" }, "join_timeout_seconds": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "idle_timeout_seconds": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "max_session_seconds": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recording": { "readOnly": true, "oneOf": [ { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "enum": [ "pending", "recording", "processing", "expired" ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "const": "ready" }, "mediaType": { "type": "string", "enum": [ "audio/mp4", "video/mp4", "audio/ogg", "video/webm" ] }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status", "mediaType", "sizeBytes", "durationMs" ], "additionalProperties": false }, { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "const": "failed" }, "errorCode": { "type": "string", "enum": [ "recording_failed", "recording_unavailable" ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status", "errorCode" ], "additionalProperties": false } ] }, "recording_mode": { "readOnly": true, "type": "string", "enum": [ "off", "audio", "video", "audio_video", "participants", "tracks" ], "description": "Server-owned recording policy; omitted means off. Legacy audio includes user and avatar audio. participants saves one continuous audio/video file per participant, without mixing their voices. tracks saves each published participant audio/video track separately; list recordings by session after capture." }, "recordings": { "readOnly": true, "maxItems": 2, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "enum": [ "pending", "recording", "processing", "expired" ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "const": "ready" }, "mediaType": { "type": "string", "enum": [ "audio/mp4", "video/mp4", "audio/ogg", "video/webm" ] }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status", "mediaType", "sizeBytes", "durationMs" ], "additionalProperties": false }, { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "const": "failed" }, "errorCode": { "type": "string", "enum": [ "recording_failed", "recording_unavailable" ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status", "errorCode" ], "additionalProperties": false } ] } }, "connection_history": { "readOnly": true, "type": "object", "properties": { "endpoint": { "type": "string", "format": "starts_with", "pattern": "^https:\\/\\/.*" }, "token": { "type": "string", "minLength": 32, "maxLength": 4096 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "endpoint", "token", "expiresAt" ], "additionalProperties": false } }, "required": [ "status", "session_id", "room_name", "livekit_url", "participant_token", "participant_identity", "agent_name", "capacity_pool", "reservation_expires_at", "max_sessions_per_gpu", "stt_mode", "room_created", "dispatch_created", "join_timeout_seconds", "idle_timeout_seconds", "max_session_seconds" ], "additionalProperties": false }, "LiveKitCapacitySnapshot": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capacity_pool": { "type": "string", "minLength": 1 }, "agent_name": { "type": "string", "minLength": 1 }, "max_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "max_sessions_per_gpu": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "worker_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "active_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reserved_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "observed_worker_active_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "available_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "queue_size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "admission_open": { "type": "boolean" }, "recommended_retry_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "load": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "capacity_pool", "agent_name", "max_sessions", "max_sessions_per_gpu", "worker_count", "active_sessions", "reserved_sessions", "observed_worker_active_sessions", "available_sessions", "queue_size", "admission_open", "recommended_retry_ms", "load" ], "additionalProperties": false }, "CapacityBusyResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1 }, "capacity": { "type": "object", "properties": { "capacity_pool": { "type": "string", "minLength": 1 }, "agent_name": { "type": "string", "minLength": 1 }, "max_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "max_sessions_per_gpu": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "worker_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "active_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reserved_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "observed_worker_active_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "available_sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "queue_size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "admission_open": { "type": "boolean" }, "recommended_retry_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "load": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "capacity_pool", "agent_name", "max_sessions", "max_sessions_per_gpu", "worker_count", "active_sessions", "reserved_sessions", "observed_worker_active_sessions", "available_sessions", "queue_size", "admission_open", "recommended_retry_ms", "load" ], "additionalProperties": false }, "queue_size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "queue_ticket_id": { "type": "string", "minLength": 1 }, "queue_position": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "recommended_retry_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "message", "capacity", "queue_size", "recommended_retry_ms" ], "additionalProperties": false }, "LiveKitSessionReleaseRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "session_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "queue_ticket_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "reason": { "type": "string", "enum": [ "page_hide", "disconnected", "superseded", "unmount", "manual", "idle_timeout" ] }, "capacity_pool": { "type": "string", "minLength": 1, "maxLength": 80 } }, "additionalProperties": false, "if": { "not": { "required": [ "session_id" ] } }, "then": { "required": [ "queue_ticket_id" ] } }, "InputSource": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "text", "client_stt", "server_stt", "unknown" ], "description": "Input source. Missing legacy provenance is unknown, never implicitly text." }, "DeclaredInputSource": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "text", "client_stt" ], "description": "Optional client declaration; a client cannot declare server_stt or unknown." }, "InputSourceDeclarationScope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "turn", "adapter" ] }, "InputProvenance": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "observed_source": { "type": "string", "enum": [ "text", "client_stt", "server_stt", "unknown" ], "description": "Source observed at ingress, kept separate from the client's declaration. SDK sendTurn observes text even when an application declares client_stt." }, "observed_by": { "type": "string", "enum": [ "sdk", "worker", "unknown" ] }, "declared_source": { "type": "string", "enum": [ "text", "client_stt" ], "description": "Optional client declaration; a client cannot declare server_stt or unknown." }, "declaration_scope": { "type": "string", "enum": [ "turn", "adapter" ] }, "ingress": { "type": "string", "enum": [ "room_text", "room_audio_stt", "unknown" ] } }, "required": [ "version", "observed_source", "observed_by", "ingress" ], "additionalProperties": {}, "description": "Optional per-user-segment input provenance. A signed webhook authenticates delivery; it does not independently verify a client's declaration. Missing legacy provenance must remain absent." }, "TranscriptSegment": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string" }, "ts": { "type": "number" }, "interrupted": { "description": "The assistant was interrupted; text contains only what was spoken.", "type": "boolean" }, "message_id": { "description": "Optional user message identity.", "type": "string", "minLength": 1, "maxLength": 200 }, "turn_id": { "description": "Optional user turn identity from rta.turn_id.", "type": "string", "minLength": 1, "maxLength": 200 }, "retry_of_turn_id": { "description": "Original user turn identity from rta.retry_of_turn_id, present only for an explicit retry.", "type": "string", "minLength": 1, "maxLength": 200 }, "input_source": { "description": "Resolved user input source. A valid client declaration may resolve room text as client_stt; observed evidence remains in input_provenance. Absent on legacy segments; never defaults to text.", "type": "string", "enum": [ "text", "client_stt", "server_stt", "unknown" ] }, "input_provenance": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "observed_source": { "type": "string", "enum": [ "text", "client_stt", "server_stt", "unknown" ], "description": "Source observed at ingress, kept separate from the client's declaration. SDK sendTurn observes text even when an application declares client_stt." }, "observed_by": { "type": "string", "enum": [ "sdk", "worker", "unknown" ] }, "declared_source": { "type": "string", "enum": [ "text", "client_stt" ], "description": "Optional client declaration; a client cannot declare server_stt or unknown." }, "declaration_scope": { "type": "string", "enum": [ "turn", "adapter" ] }, "ingress": { "type": "string", "enum": [ "room_text", "room_audio_stt", "unknown" ] } }, "required": [ "version", "observed_source", "observed_by", "ingress" ], "additionalProperties": {}, "description": "Optional per-user-segment input provenance. A signed webhook authenticates delivery; it does not independently verify a client's declaration. Missing legacy provenance must remain absent." } }, "required": [ "role", "text", "ts" ], "additionalProperties": {} }, "TranscriptToolCall": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "call_id": { "type": "string" }, "arguments": { "type": "string", "description": "Raw JSON arguments text; may be truncated, so it need not parse as JSON." }, "ts": { "type": "number" }, "ok": { "description": "Absent when the call produced nothing the model saw.", "type": "boolean" }, "result": { "type": "string" }, "error": { "type": "string" }, "duration_ms": { "type": "number" } }, "required": [ "name", "call_id", "arguments", "ts" ], "additionalProperties": {}, "description": "Tool call history; arguments and result/error text may be truncated." }, "TranscriptPayload": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string", "const": "session.transcript" }, "session_id": { "type": "string" }, "avatar_id": { "type": "string" }, "mode": { "type": "string", "enum": [ "avatar", "voice" ] }, "started_at": { "type": "number" }, "ended_at": { "type": "number" }, "seconds": { "type": "number", "description": "Session duration in seconds." }, "truncated": { "type": "boolean", "description": "True when the transcript buffer overflowed and segments are partial." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string" }, "ts": { "type": "number" }, "interrupted": { "description": "The assistant was interrupted; text contains only what was spoken.", "type": "boolean" }, "message_id": { "description": "Optional user message identity.", "type": "string", "minLength": 1, "maxLength": 200 }, "turn_id": { "description": "Optional user turn identity from rta.turn_id.", "type": "string", "minLength": 1, "maxLength": 200 }, "retry_of_turn_id": { "description": "Original user turn identity from rta.retry_of_turn_id, present only for an explicit retry.", "type": "string", "minLength": 1, "maxLength": 200 }, "input_source": { "description": "Resolved user input source. A valid client declaration may resolve room text as client_stt; observed evidence remains in input_provenance. Absent on legacy segments; never defaults to text.", "type": "string", "enum": [ "text", "client_stt", "server_stt", "unknown" ] }, "input_provenance": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "observed_source": { "type": "string", "enum": [ "text", "client_stt", "server_stt", "unknown" ], "description": "Source observed at ingress, kept separate from the client's declaration. SDK sendTurn observes text even when an application declares client_stt." }, "observed_by": { "type": "string", "enum": [ "sdk", "worker", "unknown" ] }, "declared_source": { "type": "string", "enum": [ "text", "client_stt" ], "description": "Optional client declaration; a client cannot declare server_stt or unknown." }, "declaration_scope": { "type": "string", "enum": [ "turn", "adapter" ] }, "ingress": { "type": "string", "enum": [ "room_text", "room_audio_stt", "unknown" ] } }, "required": [ "version", "observed_source", "observed_by", "ingress" ], "additionalProperties": {}, "description": "Optional per-user-segment input provenance. A signed webhook authenticates delivery; it does not independently verify a client's declaration. Missing legacy provenance must remain absent." } }, "required": [ "role", "text", "ts" ], "additionalProperties": {} } }, "tool_calls": { "description": "Optional tool call sidecar; absent when no tools ran.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "call_id": { "type": "string" }, "arguments": { "type": "string", "description": "Raw JSON arguments text; may be truncated, so it need not parse as JSON." }, "ts": { "type": "number" }, "ok": { "description": "Absent when the call produced nothing the model saw.", "type": "boolean" }, "result": { "type": "string" }, "error": { "type": "string" }, "duration_ms": { "type": "number" } }, "required": [ "name", "call_id", "arguments", "ts" ], "additionalProperties": {}, "description": "Tool call history; arguments and result/error text may be truncated." } }, "tool_calls_truncated": { "description": "True when the tool call buffer overflowed and its tail is missing.", "type": "boolean" }, "client_metadata": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "maxProperties": 16, "description": "Mint-time client_metadata echoed verbatim; an empty object when none was provided." } }, "required": [ "type", "session_id", "avatar_id", "mode", "started_at", "ended_at", "seconds", "truncated", "segments", "client_metadata" ], "additionalProperties": {}, "description": "Signed end-of-call transcript sent directly by the worker to transcript_webhook.url after capacity release. Optional provenance is additive; legacy payloads remain valid." }, "Avatar": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 8, "maxLength": 80 }, "tenantId": { "type": "string", "minLength": 8, "maxLength": 80 }, "displayName": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "image", "video" ] }, "modelId": { "type": "string", "enum": [ "realtime-avatar-live-v1", "realtime-avatar-video-v1" ] }, "sourceAssetId": { "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 80 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "preprocessing", "ready", "failed", "disabled", "deleted" ] }, "error": { "type": [ "string", "null" ] }, "idleVideoStatus": { "type": "string", "enum": [ "none", "queued", "generating", "ready", "failed" ] }, "defaultVoiceId": { "type": [ "string", "null" ] }, "llm": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "local", "gemini", "openai" ] }, "model": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "provider" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "tenantId", "displayName", "sourceKind", "modelId", "sourceAssetId", "status", "error", "idleVideoStatus", "defaultVoiceId", "llm", "createdAt", "updatedAt" ], "additionalProperties": false }, "CreateAvatarRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceKind": { "default": "image", "type": "string", "enum": [ "image", "video" ], "description": "`image` is how avatars are created: upload a portrait, and the platform generates the looping source video and the motion library from it. `video` is CLOSED — it survives in this enum for a handful of grandfathered tenants, and `createAvatar` answers everyone else `422` (\"Creating from a supplied video is closed\"). The gate is a per-tenant flag that fails closed, so treat `video` as unavailable unless you already know yours is on." }, "modelId": { "type": "string", "enum": [ "realtime-avatar-live-v1", "realtime-avatar-video-v1" ], "description": "Omit it. This is not a choice between renderers — the model is DERIVED from `sourceKind` (`image` → `realtime-avatar-live-v1`, `video` → `realtime-avatar-video-v1`), and sending one that disagrees with your `sourceKind` is `422 Avatar model is not compatible with its source kind`. So an explicit value can only ever restate what the source already decided, or fail. It follows that `realtime-avatar-video-v1` is unreachable on the `image` lane everyone uses: it needs `sourceKind: \"video\"`, which is closed." }, "sourceAssetId": { "type": "string", "minLength": 8, "maxLength": 80 }, "motionPrompt": { "type": "string", "maxLength": 1200 }, "defaultVoiceId": { "type": "string", "minLength": 8, "maxLength": 160 }, "voice": { "type": "object", "properties": { "auto_description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "voice": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "cartesia", "fish" ] }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 240 }, "model": { "type": "string", "minLength": 1, "maxLength": 120 }, "speed": { "anyOf": [ { "type": "number", "minimum": 0.5, "maximum": 2 }, { "type": "null" } ] }, "emotion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 16 }, { "type": "null" } ] } }, "required": [ "provider", "voice_id" ], "additionalProperties": false } }, "additionalProperties": false, "anyOf": [ { "required": [ "auto_description" ] }, { "required": [ "voice" ] } ] }, "llm": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "local", "gemini", "openai" ] }, "model": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "provider" ], "additionalProperties": false }, "settings": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "metadata": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "displayName" ], "additionalProperties": false }, "UpdateAvatarRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "defaultVoiceId": { "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 160 }, { "type": "null" } ] }, "llm": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "local", "gemini", "openai" ] }, "model": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "provider" ], "additionalProperties": false }, { "type": "null" } ] }, "llmProvider": { "type": "string", "enum": [ "local", "gemini", "openai" ] }, "llmModel": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "persona": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "personality": { "default": "", "type": "string", "maxLength": 4000 }, "background": { "default": "", "type": "string", "maxLength": 8000 }, "replyStyle": { "default": "short, warm, specific, and spoken", "type": "string", "maxLength": 1000 } }, "additionalProperties": false }, "artDirection": { "type": "string", "maxLength": 2500 }, "stylePreset": { "type": "string", "enum": [ "cinematic-founder", "editorial-companion", "warm-anime", "luxury-realism", "soft-3d", "noir-avatar" ] }, "portraitUrl": { "type": "string", "format": "uri", "description": "Dashboard-only. `updateAvatar` needs a request/env context to pull the image into tenant storage, and the public route does not supply one, so sending this here is always `400 Portrait updates are not available on this route`. To change the portrait over this API, register the image with `POST /v1/assets` or `POST /v1/assets/remote` and PATCH the returned id as `sourceAssetId`, which is the swap lane and does work." }, "sourceAssetId": { "type": "string", "minLength": 1 }, "anchorTimeMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sourceReview": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false } }, "additionalProperties": false, "minProperties": 1 }, "CreateApiKeyRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "environment": { "description": "Deprecated. Accepted for older clients but ignored; all new keys use the same tic_ format.", "type": "string", "enum": [ "live", "test" ] }, "scopes": { "default": [ "realtime:write", "credits:read", "avatars:read" ], "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "enum": [ "*", "api_keys:write", "credits:read", "avatars:read", "avatars:write", "realtime:write", "usage:read", "recordings:read", "usage:write" ] } }, "spendLimitCreditMicros": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false }, "CreateApiKeyResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 8, "maxLength": 80 }, "keyId": { "type": "string", "minLength": 8, "maxLength": 64 }, "tenantId": { "type": "string", "minLength": 8, "maxLength": 80 }, "name": { "type": "string" }, "redactedKey": { "type": "string" }, "canReveal": { "default": false, "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "*", "api_keys:write", "credits:read", "avatars:read", "avatars:write", "realtime:write", "usage:read", "recordings:read", "usage:write" ] } }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "spendLimitCreditMicros": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ] }, "apiKey": { "type": "string", "format": "starts_with", "pattern": "^tic_.*" } }, "required": [ "id", "keyId", "tenantId", "name", "redactedKey", "canReveal", "scopes", "status", "spendLimitCreditMicros", "createdAt", "expiresAt", "apiKey" ], "additionalProperties": false }, "Asset": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 8, "maxLength": 80 }, "tenantId": { "type": "string", "minLength": 8, "maxLength": 80 }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "status": { "type": "string", "enum": [ "pending_upload", "uploaded", "processing", "ready", "failed", "deleted" ] }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": [ "string", "null" ] }, "publicUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "tenantId", "kind", "status", "contentType", "sizeBytes", "sha256", "publicUrl", "createdAt", "updatedAt" ], "additionalProperties": false }, "AssetList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } }, "required": [ "data" ], "additionalProperties": false }, "CreateRemoteAssetRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "remoteUrl": { "type": "string", "format": "uri" }, "originalFilename": { "type": "string", "minLength": 1, "maxLength": 240 }, "metadata": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "kind", "remoteUrl" ], "additionalProperties": false }, "CreateSceneRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "An https URL the builder can fetch. Hosts are allowlisted by the builder." }, "md5": { "description": "MD5 of the clip bytes. With bytes, lets an already-built scene answer ready without a download.", "type": "string", "pattern": "^[0-9a-f]{32}$" }, "bytes": { "description": "Clip size in bytes (at most 64 MiB).", "type": "integer", "exclusiveMinimum": 0, "maximum": 67108864 } }, "required": [ "url" ], "additionalProperties": false, "description": "The first clip. Played forward over its full length." }, "continuation": { "description": "Optional return clip appended after the first. When its last frame matches the first clip's first frame, the loop closes seamlessly.", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "An https URL the builder can fetch. Hosts are allowlisted by the builder." }, "md5": { "description": "MD5 of the clip bytes. With bytes, lets an already-built scene answer ready without a download.", "type": "string", "pattern": "^[0-9a-f]{32}$" }, "bytes": { "description": "Clip size in bytes (at most 64 MiB).", "type": "integer", "exclusiveMinimum": 0, "maximum": 67108864 } }, "required": [ "url" ], "additionalProperties": false }, "profile": { "type": "string", "enum": [ "scene-v0" ] } }, "required": [ "source", "profile" ], "additionalProperties": false }, "SceneState": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "building" }, "scene_id": { "type": "string", "pattern": "^rtav_[0-9a-f]{32}$", "description": "The prepared scene's artifact id, as returned by POST /v1/scenes when status is ready." }, "timings": { "type": "object", "properties": { "download_ms": { "type": "number", "minimum": 0 }, "decode_ms": { "type": "number", "minimum": 0 }, "geometry_ms": { "type": "number", "minimum": 0 }, "write_ms": { "type": "number", "minimum": 0 }, "total_ms": { "type": "number", "minimum": 0 } }, "additionalProperties": false } }, "required": [ "status", "scene_id" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "ready" }, "scene_id": { "type": "string", "pattern": "^rtav_[0-9a-f]{32}$", "description": "The prepared scene's artifact id, as returned by POST /v1/scenes when status is ready." }, "video_cache_id": { "type": "string", "pattern": "^rtav_[0-9a-f]{32}$", "description": "The prepared scene's artifact id, as returned by POST /v1/scenes when status is ready." }, "fps": { "type": "number", "exclusiveMinimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "first_frames": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "total_frames": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "duration_s": { "type": "number", "exclusiveMinimum": 0 }, "timings": { "type": "object", "properties": { "download_ms": { "type": "number", "minimum": 0 }, "decode_ms": { "type": "number", "minimum": 0 }, "geometry_ms": { "type": "number", "minimum": 0 }, "write_ms": { "type": "number", "minimum": 0 }, "total_ms": { "type": "number", "minimum": 0 } }, "additionalProperties": false } }, "required": [ "status", "scene_id" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "failed" }, "scene_id": { "anyOf": [ { "type": "string", "pattern": "^rtav_[0-9a-f]{32}$", "description": "The prepared scene's artifact id, as returned by POST /v1/scenes when status is ready." }, { "type": "string", "const": "unresolved" } ], "description": "The scene id, or \"unresolved\" when the download failed before any byte was hashed and the request carried no md5 and bytes." }, "error": { "type": "string", "enum": [ "source_unreachable", "source_unusable", "source_mismatch", "build_failed" ] }, "timings": { "type": "object", "properties": { "download_ms": { "type": "number", "minimum": 0 }, "decode_ms": { "type": "number", "minimum": 0 }, "geometry_ms": { "type": "number", "minimum": 0 }, "write_ms": { "type": "number", "minimum": 0 }, "total_ms": { "type": "number", "minimum": 0 } }, "additionalProperties": false } }, "required": [ "status", "scene_id" ], "additionalProperties": false } ] }, "CreditBalance": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tenantId": { "type": "string", "minLength": 8, "maxLength": 80 }, "balanceCreditMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reservedCreditMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "availableCreditMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lifetimeGrantedCreditMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lifetimeUsedCreditMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "type": "string" } }, "required": [ "tenantId", "balanceCreditMicros", "reservedCreditMicros", "availableCreditMicros", "lifetimeGrantedCreditMicros", "lifetimeUsedCreditMicros", "updatedAt" ], "additionalProperties": false }, "ListUsageSessionsResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 8, "maxLength": 80 }, "releaseIdentity": { "readOnly": true, "description": "Returned only for X-RTA-Release-Evidence: 1. Omitted by default for strict client compatibility. Evidence is stored against this session; missing evidence remains null.", "type": "object", "properties": { "deploymentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "workerRevision": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{40}$" }, { "type": "null" } ] }, "provenance": { "type": "object", "properties": { "deploymentSource": { "type": "string", "const": "cloudflare-worker-version" }, "workerSource": { "anyOf": [ { "type": "string", "const": "authenticated-worker-heartbeat" }, { "type": "null" } ] }, "workerId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "podStartedAtMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "workerObservedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "deploymentSource", "workerSource", "workerId", "podStartedAtMs", "workerObservedAt" ], "additionalProperties": false } }, "required": [ "deploymentId", "workerRevision", "provenance" ], "additionalProperties": false }, "avatarId": { "type": [ "string", "null" ] }, "avatarName": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "reserved", "started", "released", "failed" ] }, "startedAt": { "type": [ "string", "null" ] }, "endedAt": { "type": [ "string", "null" ] }, "activeSeconds": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "billedCreditMicros": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string" } }, "required": [ "sessionId", "avatarId", "avatarName", "status", "startedAt", "endedAt", "activeSeconds", "billedCreditMicros", "metadata", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "data", "nextCursor", "from", "to" ], "additionalProperties": false }, "Recording": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "enum": [ "pending", "recording", "processing", "expired" ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "const": "ready" }, "mediaType": { "type": "string", "enum": [ "audio/mp4", "video/mp4", "audio/ogg", "video/webm" ] }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status", "mediaType", "sizeBytes", "durationMs" ], "additionalProperties": false }, { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "const": "failed" }, "errorCode": { "type": "string", "enum": [ "recording_failed", "recording_unavailable" ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status", "errorCode" ], "additionalProperties": false } ] }, "ListRecordingsResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "enum": [ "pending", "recording", "processing", "expired" ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "const": "ready" }, "mediaType": { "type": "string", "enum": [ "audio/mp4", "video/mp4", "audio/ogg", "video/webm" ] }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status", "mediaType", "sizeBytes", "durationMs" ], "additionalProperties": false }, { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "recordingId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video", "audio_video" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "retainedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "participant": { "type": "object", "properties": { "participantIdentity": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "user", "avatar" ] } }, "required": [ "participantIdentity", "role" ], "additionalProperties": false }, "mediaStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaEndedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mediaStartOffsetMs": { "description": "First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mediaMutedIntervalsMs": { "description": "Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.", "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "startMs", "endMs" ], "additionalProperties": false } }, "status": { "type": "string", "const": "failed" }, "errorCode": { "type": "string", "enum": [ "recording_failed", "recording_unavailable" ] } }, "required": [ "sessionId", "recordingId", "mode", "createdAt", "retainedUntil", "status", "errorCode" ], "additionalProperties": false } ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false }, "RecordingAccessResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "recordingId": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "recordingId", "url", "expiresAt" ], "additionalProperties": false }, "ConnectionHistoryResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "observations": { "maxItems": 240, "type": "array", "items": { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 240 }, "elapsedMs": { "type": "integer", "minimum": 0, "maximum": 86400000 }, "clientObservedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "connectionState": { "type": "string", "enum": [ "disconnected", "connecting", "connected", "reconnecting", "signalReconnecting" ] }, "localQuality": { "type": "string", "enum": [ "excellent", "good", "poor", "lost", "unknown" ] }, "audioQuality": { "anyOf": [ { "type": "string", "enum": [ "excellent", "good", "poor", "lost", "unknown" ] }, { "type": "null" } ] }, "videoQuality": { "anyOf": [ { "type": "string", "enum": [ "excellent", "good", "poor", "lost", "unknown" ] }, { "type": "null" } ] } }, "required": [ "sequence", "elapsedMs", "clientObservedAt", "connectionState", "localQuality", "audioQuality", "videoQuality" ], "additionalProperties": false } } }, "required": [ "sessionId", "observations" ], "additionalProperties": false }, "ListAvatarsResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 8, "maxLength": 80 }, "tenantId": { "type": "string", "minLength": 8, "maxLength": 80 }, "displayName": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "image", "video" ] }, "modelId": { "type": "string", "enum": [ "realtime-avatar-live-v1", "realtime-avatar-video-v1" ] }, "sourceAssetId": { "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 80 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "preprocessing", "ready", "failed", "disabled", "deleted" ] }, "error": { "type": [ "string", "null" ] }, "idleVideoStatus": { "type": "string", "enum": [ "none", "queued", "generating", "ready", "failed" ] }, "defaultVoiceId": { "type": [ "string", "null" ] }, "llm": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "local", "gemini", "openai" ] }, "model": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "provider" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "tenantId", "displayName", "sourceKind", "modelId", "sourceAssetId", "status", "error", "idleVideoStatus", "defaultVoiceId", "llm", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "ListAvatarClipsResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "generating", "ready", "failed" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "generated", "uploaded" ] }, "uploadAssetId": { "type": [ "string", "null" ] }, "motionPrompt": { "type": [ "string", "null" ] }, "durationSeconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "anchorVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "poseCheck": { "anyOf": [ { "type": "object", "properties": { "verdict": { "type": "object", "properties": { "sameSubject": { "type": "boolean" }, "firstFrameMatchesAnchor": { "type": "boolean" }, "lastFrameMatchesAnchor": { "type": "boolean" }, "framingComparable": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "sameSubject", "firstFrameMatchesAnchor", "lastFrameMatchesAnchor", "framingComparable", "confidence" ], "additionalProperties": false }, "issues": { "type": "array", "items": { "type": "string" } }, "firstFrameUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "lastFrameUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "verdict", "issues", "firstFrameUrl", "lastFrameUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "clipId", "status", "url", "source", "uploadAssetId", "motionPrompt", "durationSeconds", "anchorVersion", "poseCheck", "error", "createdAt", "updatedAt" ], "additionalProperties": false } }, "avatarId": { "type": "string" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "anchorVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "anchor": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "source": { "type": "string", "enum": [ "portrait", "source_frame" ] }, "timeMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "url", "source", "timeMs" ], "additionalProperties": false }, { "type": "null" } ] }, "clipLibraryEligible": { "type": "boolean" }, "defaultSourceAssetId": { "type": [ "string", "null" ] }, "behavior": { "type": "object", "properties": { "idle": { "type": "object", "properties": { "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "weights": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } } }, "required": [ "clips" ], "additionalProperties": false }, "on": { "type": "object", "properties": { "userSpeechStarted": { "type": "object", "properties": { "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } }, "required": [ "clips" ], "additionalProperties": false } }, "additionalProperties": false }, "actions": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 512 }, "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } }, "required": [ "description", "clips" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "data", "avatarId", "revision", "anchorVersion", "anchor", "clipLibraryEligible", "defaultSourceAssetId", "behavior" ], "additionalProperties": false }, "ReviewAvatarClipRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clipId": { "type": "string", "minLength": 1, "maxLength": 64 }, "uploadAssetId": { "type": "string", "minLength": 1 }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expectedAnchorVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "reason": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "clipId", "uploadAssetId", "expectedRevision", "expectedAnchorVersion", "reason" ] }, "PutAvatarClipsRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "clips": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "source": { "anyOf": [ { "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "assetId" ], "additionalProperties": false }, { "type": "object", "properties": { "motionPrompt": { "type": "string", "minLength": 1, "maxLength": 1200 }, "durationSeconds": { "type": "integer", "minimum": 4, "maximum": 8 } }, "required": [ "motionPrompt" ], "additionalProperties": false } ] } }, "required": [ "source" ], "additionalProperties": false } }, "idle": { "type": "object", "properties": { "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "weights": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } } }, "required": [ "clips" ], "additionalProperties": false }, "on": { "type": "object", "properties": { "userSpeechStarted": { "type": "object", "properties": { "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } }, "required": [ "clips" ], "additionalProperties": false } }, "additionalProperties": false }, "actions": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 512 }, "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } }, "required": [ "description", "clips" ], "additionalProperties": false } } }, "required": [ "expectedRevision", "clips" ], "additionalProperties": false }, "PutAvatarClipsResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "generating", "ready", "failed" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "generated", "uploaded" ] }, "uploadAssetId": { "type": [ "string", "null" ] }, "motionPrompt": { "type": [ "string", "null" ] }, "durationSeconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "anchorVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "poseCheck": { "anyOf": [ { "type": "object", "properties": { "verdict": { "type": "object", "properties": { "sameSubject": { "type": "boolean" }, "firstFrameMatchesAnchor": { "type": "boolean" }, "lastFrameMatchesAnchor": { "type": "boolean" }, "framingComparable": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "sameSubject", "firstFrameMatchesAnchor", "lastFrameMatchesAnchor", "framingComparable", "confidence" ], "additionalProperties": false }, "issues": { "type": "array", "items": { "type": "string" } }, "firstFrameUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "lastFrameUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "verdict", "issues", "firstFrameUrl", "lastFrameUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "clipId", "status", "url", "source", "uploadAssetId", "motionPrompt", "durationSeconds", "anchorVersion", "poseCheck", "error", "createdAt", "updatedAt" ], "additionalProperties": false } }, "avatarId": { "type": "string" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "anchorVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "anchor": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "source": { "type": "string", "enum": [ "portrait", "source_frame" ] }, "timeMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "url", "source", "timeMs" ], "additionalProperties": false }, { "type": "null" } ] }, "clipLibraryEligible": { "type": "boolean" }, "defaultSourceAssetId": { "type": [ "string", "null" ] }, "behavior": { "type": "object", "properties": { "idle": { "type": "object", "properties": { "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "weights": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } } }, "required": [ "clips" ], "additionalProperties": false }, "on": { "type": "object", "properties": { "userSpeechStarted": { "type": "object", "properties": { "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } }, "required": [ "clips" ], "additionalProperties": false } }, "additionalProperties": false }, "actions": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 512 }, "clips": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } } }, "required": [ "description", "clips" ], "additionalProperties": false } } }, "additionalProperties": false }, "plan": { "type": "object", "properties": { "kept": { "type": "array", "items": { "type": "string" } }, "queued": { "type": "array", "items": { "type": "string" } }, "retired": { "type": "array", "items": { "type": "string" } } }, "required": [ "kept", "queued", "retired" ], "additionalProperties": false } }, "required": [ "data", "avatarId", "revision", "anchorVersion", "anchor", "clipLibraryEligible", "defaultSourceAssetId", "behavior", "plan" ], "additionalProperties": false }, "PutAvatarLoopRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "motionPrompt": { "type": "string", "minLength": 1, "maxLength": 1200 } }, "required": [ "motionPrompt" ], "additionalProperties": false }, "PutAvatarLoopResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "avatarId": { "type": "string" }, "loopStatus": { "type": "string", "enum": [ "generating", "ready", "failed" ] }, "motionPrompt": { "type": "string" }, "servingUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "avatarId", "loopStatus", "motionPrompt", "servingUrl" ], "additionalProperties": false }, "OkResponse": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false }, "Error": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message. Not a stable contract — switch on `code` or `status`." }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Repeats the HTTP status in the body. Always present." }, "code": { "type": "string", "description": "Machine-readable discriminator. ALWAYS present: a failure that names its own — billing, clip-library and loop refusals, `insufficient_scope` — carries that, and everything else carries the status's default (`unauthorized`, `not_found`, `rate_limited`, …). Switch on this rather than on `error`, whose wording is not a contract. The set is open and grows with the API; the codes a given endpoint can return are documented with that endpoint at https://realtimeavatar.ai/docs/api-reference." }, "documentation": { "type": "string", "format": "uri", "description": "Where to read how to resolve a failure of this class — the authentication guide for 401/403, the API reference otherwise. Always present." }, "retryable": { "description": "Set when the failure is worth retrying as-is.", "type": "boolean" }, "requestId": { "description": "Server-generated correlation ID, also returned in X-Request-ID on correlated failures. Quote this when contacting support. Detailed diagnostics require separate operational access.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requiredScope": { "description": "Present on `403 insufficient_scope` — the one scope this operation needed and the key did not carry. Repeated in the `WWW-Authenticate` challenge as `scope=`.", "type": "string", "enum": [ "*", "api_keys:write", "credits:read", "avatars:read", "avatars:write", "realtime:write", "usage:read", "recordings:read", "usage:write" ] }, "grantedScopes": { "description": "Present alongside `requiredScope` — the scopes the presented key does carry.", "type": "array", "items": { "type": "string", "enum": [ "*", "api_keys:write", "credits:read", "avatars:read", "avatars:write", "realtime:write", "usage:read", "recordings:read", "usage:write" ] } }, "billingUrl": { "description": "Present on 402 — where to send the user to top up.", "type": "string" }, "maxConcurrentSessions": { "description": "On concurrency_limit_reached: the workspace's concurrent session limit.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "liveSessions": { "description": "Legacy concurrency count: occupied reservations, including active, connecting and starting sessions. Not the number of active conversations.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeSessions": { "description": "On concurrency_limit_reached: counted reservations with started media, observed at refusal.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connectingSessions": { "description": "On concurrency_limit_reached: counted reservations with an attached session that has not started media.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pendingSessions": { "description": "On concurrency_limit_reached: counted in-flight starts with no attached session yet.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "error", "status", "code", "documentation" ], "additionalProperties": {} } } }, "security": [ { "bearerAuth": [] } ], "webhooks": { "session.transcript": { "post": { "operationId": "receiveSessionTranscript", "summary": "Receive the signed end-of-call transcript", "description": "The worker POSTs directly to the application's mint-time transcript_webhook.url after releasing session capacity. No transcript is stored by the platform. A session with no committed segments and no tool calls sends nothing. Verify HMAC-SHA256 with transcript_webhook.secret over the timestamp, a literal dot, and the raw request body before parsing; reject stale timestamps. Delivery is best-effort and may repeat; consumers should tolerate duplicate session_id values. No delivery or retry guarantee is made. Input provenance is optional on user segments; missing legacy provenance must not be inferred as text.", "security": [], "parameters": [ { "name": "x-rta-signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^v1=[0-9a-f]{64}$" }, "description": "v1= followed by the hex HMAC-SHA256 of ., keyed by transcript_webhook.secret. Compare in constant time." }, { "name": "x-rta-timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Timestamp string used verbatim in the signed message. Verify freshness to bound replay." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptPayload" } } } }, "responses": { "2XX": { "description": "Receipt acknowledged by the application." }, "default": { "description": "Application response; delivery and retries are best-effort." } } } } }, "x-error-semantics": { "description": "What a failure `code` means to the caller. `statuses` is the set of HTTP statuses a code may legitimately accompany — a code arriving on any other status is a mismatch and must be answered by the status alone. `message` is authored product copy safe to show a user. `retryable` says whether the same request is worth sending again. Codes listed in `x-error-codes-uncopied` are recognised by the platform but have their copy written elsewhere, because the sentence names a number this table cannot know (a plan ceiling, an amount owed); treat them as known, and prefer the server's own `message`.", "codes": { "bad_request": { "statuses": [ 400 ], "message": "Check the request and try again.", "retryable": false }, "unauthorized": { "statuses": [ 401 ], "message": "Authentication is required to use Realtime Avatar.", "retryable": false }, "payment_required": { "statuses": [ 402 ], "message": "Add credits to continue using realtime avatars.", "retryable": false }, "forbidden": { "statuses": [ 403 ], "message": "This API key does not have access to that action.", "retryable": false }, "not_found": { "statuses": [ 404 ], "message": "We could not find that avatar or resource.", "retryable": false }, "method_not_allowed": { "statuses": [ 405 ], "message": "This request method is not supported.", "retryable": false }, "not_acceptable": { "statuses": [ 406 ], "message": "The requested response format is not supported.", "retryable": false }, "request_aborted": { "statuses": [ 408 ], "message": "The session request was cancelled.", "retryable": false }, "conflict": { "statuses": [ 409 ], "message": "That request is already in progress. Try again in a moment.", "retryable": true }, "length_required": { "statuses": [ 411 ], "message": "A request content length is required.", "retryable": false }, "payload_too_large": { "statuses": [ 413 ], "message": "The request is too large.", "retryable": false }, "unprocessable_entity": { "statuses": [ 422 ], "message": "Check the request and try again.", "retryable": false }, "rate_limited": { "statuses": [ 429 ], "message": "Too many realtime requests. Please slow down and retry.", "retryable": true }, "internal_error": { "statuses": [ 500 ], "message": "The session service encountered an error. Try again.", "retryable": true }, "unavailable": { "statuses": [ 503 ], "message": "Realtime Avatar is temporarily unavailable. Try again in a moment.", "retryable": true }, "insufficient_scope": { "statuses": [ 403 ], "message": "This API key is missing a required permission.", "retryable": false }, "loop_pending": { "statuses": [ 409 ], "message": "An avatar loop update is still in progress. Try again shortly.", "retryable": true }, "rate_limit_exceeded": { "statuses": [ 429 ], "message": "Too many realtime requests. Please slow down and retry.", "retryable": true }, "upstream_failed": { "statuses": [ 500, 502, 503 ], "message": "The session service could not complete the request. Try again.", "retryable": true }, "upstream_unreachable": { "statuses": [ 502, 503 ], "message": "The session service could not be reached. Try again.", "retryable": true }, "invalid_upstream_response": { "statuses": [ 502 ], "message": "The session service returned an invalid response. Try again.", "retryable": true }, "upstream_timeout": { "statuses": [ 504 ], "message": "The session service took too long to respond. Try again.", "retryable": true }, "capacity_unavailable": { "statuses": [ 503 ], "message": "Session availability could not be checked. Try again.", "retryable": true }, "session_dispatch_failed": { "statuses": [ 503 ], "message": "The avatar session could not be started. Try again.", "retryable": true }, "admission_unavailable": { "statuses": [ 503 ], "message": "Session admission is temporarily unavailable. Try again.", "retryable": true }, "service_warming": { "statuses": [ 503 ], "message": "Realtime Avatar is warming up. Try again in a moment.", "retryable": true }, "avatar_not_ready": { "statuses": [ 409 ], "message": "This avatar is still being built — it is usually ready within a minute. Try again then.", "retryable": true }, "clip_library_not_ready": { "statuses": [ 409 ], "message": "This avatar's motion clips are still rendering. Try again in a minute.", "retryable": true }, "recording_unsupported": { "statuses": [ 501 ], "message": "Session recording is not enabled for this deployment.", "retryable": false }, "recording_requires_new_room": { "statuses": [ 422 ], "message": "Recording requires a new session room. Start a fresh session to record it.", "retryable": false }, "recording_unavailable": { "statuses": [ 503 ], "message": "Session recording is temporarily unavailable. Try again in a moment.", "retryable": true } } }, "x-error-codes-uncopied": [ "capacity_busy", "concurrency_limit_reached", "insufficient_credits", "spend_limit_exceeded", "billing_required", "network_error" ], "x-error-message-shape": { "description": "A message matching any of these patterns must NOT be shown to a user; fall back to the `message` in x-error-semantics instead. Rebuild each with new RegExp(source, flags). A message that passes is truncated to maxLength characters before display.", "patterns": { "machine": { "source": "[_=<>{}\\[\\]|\\\\$`]|\\w+\\.\\w+\\.\\w|\\S:\\d|\\w\\(\\)|^\\s*(?:at|File)\\b|\\bTraceback \\(most recent call last\\)", "flags": "mu" }, "locator": { "source": "https?://|/[\\w.-]+/|[\\w.+-]+@[\\w.-]+\\.[a-z]{2,}|\\bbearer\\s|[\\r\\n]", "flags": "i" } }, "maxLength": 180 }, "paths": { "/v1/realtime/livekit/capacity": { "get": { "operationId": "getLiveKitCapacity", "description": "Free/busy snapshot of the render fleet, for deciding whether to offer a call before minting one.\n\nRequires an API key with the `realtime:write` scope.", "responses": { "200": { "description": "Capacity snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveKitCapacitySnapshot" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "realtime:write" ], "summary": "Get a capacity snapshot", "tags": [ "Realtime" ] } }, "/v1/realtime/livekit/session": { "post": { "operationId": "createLiveKitSession", "parameters": [ { "name": "X-RTA-Release-Evidence", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Send 1 to include optional session-bound releaseIdentity in this response. Without this opt-in the field is omitted for strict client compatibility. Capture and storage are independent of this header; missing evidence remains null. Older servers may ignore this header." }, { "name": "X-RTA-Observability", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "identity-v1" ] }, "description": "Send exactly identity-v1 to include optional usage_account_id on a successful mint after billing attachment. Sourced only from the platform billing hold tenant ID. Other or missing values omit the field; failures and queued responses never include it. Success responses are Cache-Control: no-store. Older servers may omit the field. Independent of X-RTA-Release-Evidence and connection_history policy." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveKitSessionRequest" } } } }, "responses": { "200": { "description": "LiveKit session grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveKitSessionGrant" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Either the workspace session limit was reached (code \"concurrency_limit_reached\", top-level maxConcurrentSessions, liveSessions, activeSessions, connectingSessions, pendingSessions), or GPU capacity is full (the queue contract). Starting and connecting sessions count toward the workspace limit. End a session or wait for pending starts to clear before retrying; avoid parallel duplicate starts. This refusal is not a queue position. Retain requestId for support.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CapacityBusyResponse" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires an API key with the `realtime:write` scope.", "x-required-scopes": [ "realtime:write" ], "summary": "Mint a realtime session", "tags": [ "Realtime" ] } }, "/v1/realtime/livekit/session/release": { "post": { "operationId": "releaseLiveKitClientSession", "description": "Releases a held capacity lease immediately (client beacon on tab-close, terminal disconnect, or a superseded reconnect) so the GPU slot is freed instead of lingering until its TTL. Idempotent.\n\nRequires an API key with the `realtime:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveKitSessionReleaseRequest" } } } }, "responses": { "200": { "description": "Released", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "realtime:write" ], "summary": "Release a session's capacity lease", "tags": [ "Realtime" ] } }, "/v1/scenes": { "post": { "operationId": "createScene", "description": "Prepare a scene: a supplied clip registered once into an artifact a session can play in place of the avatar's source video (mint with scene.video_cache_id). The id is derived from the clip's content (md5 and size), not its URL, so the same bytes give the same id; a repeat request whose md5 and bytes are already built answers ready without a download. The answered id is bound to this workspace: only a scene the workspace prepared can be read back or minted, and a mint also requires it to be ready (409 scene_not_ready otherwise). 202 while building; poll GET /v1/scenes/{sceneId}. 200 once ready or failed. A failed state carries error: source_unreachable (the bytes never arrived; retry with a bounded backoff), source_unusable (supply a different clip), source_mismatch (the bytes differ from the declared md5 or bytes) or build_failed. Its scene_id is \"unresolved\" when the download failed before any byte was hashed and the request declared no md5 and bytes.\n\nRequires an API key with the `realtime:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSceneRequest" } } } }, "responses": { "200": { "description": "Ready or failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneState" } } } }, "202": { "description": "Building", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneState" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, the tenant is not active, or scene sessions are not enabled for the workspace — code \"scene_sessions_not_enabled\", a per-workspace preview gate. Contact support to opt in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "realtime:write" ], "summary": "Prepare a scene (preview)", "tags": [ "Scenes" ] } }, "/v1/scenes/{sceneId}": { "get": { "operationId": "getScene", "description": "A scene's build state, for a scene this workspace prepared. ready carries video_cache_id and the frame facts a mint may pass through.\n\nRequires an API key with the `realtime:write` scope.", "parameters": [ { "name": "sceneId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rtav_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "Scene state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneState" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, the tenant is not active, or scene sessions are not enabled for the workspace — code \"scene_sessions_not_enabled\", a per-workspace preview gate. Contact support to opt in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No scene with this id that this workspace prepared (code \"scene_not_found\")", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "realtime:write" ], "summary": "Get a scene's build state (preview)", "tags": [ "Scenes" ] } }, "/v1/avatars": { "get": { "operationId": "listAvatars", "responses": { "200": { "description": "Avatars", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAvatarsResponse" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires an API key with the `avatars:read` scope.", "x-required-scopes": [ "avatars:read" ], "summary": "List avatars", "tags": [ "Avatars" ] }, "post": { "operationId": "createAvatar", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAvatarRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Avatar" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires an API key with the `avatars:write` scope.", "x-required-scopes": [ "avatars:write" ], "summary": "Create an avatar from a portrait", "tags": [ "Avatars" ] } }, "/v1/avatars/{avatarId}": { "get": { "operationId": "getAvatar", "parameters": [ { "name": "avatarId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Avatar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Avatar" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires an API key with the `avatars:read` scope.", "x-required-scopes": [ "avatars:read" ], "summary": "Get an avatar", "tags": [ "Avatars" ] }, "patch": { "operationId": "updateAvatar", "parameters": [ { "name": "avatarId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAvatarRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Avatar" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires an API key with the `avatars:write` scope.", "x-required-scopes": [ "avatars:write" ], "summary": "Update an avatar", "tags": [ "Avatars" ] }, "delete": { "operationId": "deleteAvatar", "parameters": [ { "name": "avatarId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted. No content." }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires an API key with the `avatars:write` scope.", "x-required-scopes": [ "avatars:write" ], "summary": "Delete an avatar", "tags": [ "Avatars" ] } }, "/v1/avatars/{avatarId}/clips": { "get": { "operationId": "listAvatarClips", "parameters": [ { "name": "avatarId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Clips", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAvatarClipsResponse" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires an API key with the `avatars:read` scope.", "x-required-scopes": [ "avatars:read" ], "summary": "List an avatar's motion clips", "tags": [ "Avatars" ] }, "put": { "operationId": "putAvatarClips", "description": "Declare the avatar's full desired clip library; see https://realtimeavatar.ai/docs/editing. The platform reconciles: unchanged clips are kept, changed or new ones re-render in the background against the avatar's pose anchor, absent ones soft-retire. 202 returns the post-apply library plus the reconcile plan. Supports Idempotency-Key replay and expectedRevision compare-and-set.\n\nRequires an API key with the `avatars:write` scope.", "parameters": [ { "name": "avatarId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays the original response byte-for-byte instead of performing the write again. Recommended on retries: a re-render is billed. Keys longer than 180 characters are IGNORED — the write proceeds without replay protection rather than failing — so keep it short.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutAvatarClipsRequest" } } } }, "responses": { "202": { "description": "Declaration accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutAvatarClipsResponse" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, the tenant is not active, or the clip-library write is not yet enabled for the tenant — code \"clip_library_not_enabled\", a per-tenant rollout gate. Contact support to opt in; until then an avatar keeps the library its creation pipeline generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "avatars:write" ], "summary": "Declare an avatar's clip library", "tags": [ "Avatars" ] } }, "/v1/avatars/{avatarId}/clips/review": { "post": { "operationId": "reviewAvatarClip", "description": "Accept an uploaded clip after human quality review. Requires avatars:write and the clip-library rollout. Revision and asset identity must match; active source swaps, unavailable assets and non-pose failures cannot be overridden. Preserves the original machine verdict and records the review before publishing the asset.\n\nRequires an API key with the `avatars:write` scope.", "parameters": [ { "name": "avatarId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewAvatarClipRequest" } } } }, "responses": { "204": { "description": "Uploaded clip accepted; cache preparation scheduled" }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "avatars:write" ], "summary": "Manually accept an uploaded clip after quality review", "tags": [ "Avatars" ] } }, "/v1/avatars/{avatarId}/loop": { "put": { "operationId": "putAvatarLoop", "description": "Re-direct the avatar's RESTING LOOP — the video she plays when nothing else is happening — from a new one-sentence description. Not a clip: a clip with role \"idle\" is a variant spliced OVER the loop, and declaring one never changes what she rests in. 202; the render takes minutes, during which she stays ready and keeps serving her previous loop (returned as servingUrl), and the swap publishes atomically once the new loop is usable. The clip library is untouched. Billed as one generation at the rendering model's rate. Needs a portrait to re-animate: 422 loop_not_generatable (terminal) on a grandfathered avatar built from a supplied video with no portrait — the gate is the portrait, not sourceKind, which reads \"video\" on every avatar once its generated loop has attached. Supports Idempotency-Key replay — send one on retries, because a repeated re-direct is a second billed render.\n\nRequires an API key with the `avatars:write` scope.", "parameters": [ { "name": "avatarId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Replays the original response byte-for-byte instead of performing the write again. Recommended on retries: a re-render is billed. Keys longer than 180 characters are IGNORED — the write proceeds without replay protection rather than failing — so keep it short.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutAvatarLoopRequest" } } } }, "responses": { "202": { "description": "Re-direct accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutAvatarLoopResponse" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "avatars:write" ], "summary": "Re-direct an avatar's resting loop", "tags": [ "Avatars" ] } }, "/v1/api-keys": { "post": { "operationId": "createApiKey", "description": "Mint a developer API key for the caller's own tenant. The plaintext key is returned in this response. Workspace owners and admins can recover eligible keys in the dashboard; recovery is not available through the developer API.\n\nRequires an API key with the `api_keys:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "Created. The plaintext key is returned on creation; workspace owners and admins can recover eligible keys in the dashboard. Recovery is not available through the developer API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "api_keys:write" ], "summary": "Mint an API key", "tags": [ "API keys" ] } }, "/v1/assets": { "get": { "operationId": "listAssets", "description": "The tenant's most recent assets, newest first.\n\nRequires an API key with the `avatars:read` scope.", "responses": { "200": { "description": "Assets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetList" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "avatars:read" ], "summary": "List assets", "tags": [ "Assets" ] }, "post": { "operationId": "uploadAsset", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The asset bytes." }, "kind": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "image", "video", "audio" ], "description": "Optional; inferred from the file when omitted. Image assets are portraits, audio assets are voice material, and video assets may be declared as uploaded motion clips with source.assetId. Video assets are not accepted as the source of a newly created Avatar." } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires an API key with the `avatars:write` scope.", "x-required-scopes": [ "avatars:write" ], "summary": "Upload an asset", "tags": [ "Assets" ] } }, "/v1/assets/remote": { "post": { "operationId": "createRemoteAsset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRemoteAssetRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires an API key with the `avatars:write` scope.", "x-required-scopes": [ "avatars:write" ], "summary": "Create an asset from a URL", "tags": [ "Assets" ] } }, "/v1/credits/balance": { "get": { "operationId": "getCreditBalance", "description": "A BALANCE, not a bill. Per-session detail for reconciliation is /v1/usage/sessions.\n\nRequires an API key with the `credits:read` scope.", "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalance" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "credits:read" ], "summary": "Get the credit balance", "tags": [ "Credits" ] } }, "/v1/sessions/{sessionId}/connection-history": { "get": { "operationId": "getConnectionHistory", "description": "Read client-reported LiveKit connection changes for an owned session. No observations means no received data, not a healthy connection. Client timestamps are approximate and distinct from recording time.\n\nRequires an API key with the `usage:read` scope.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session connection history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionHistoryResponse" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "usage:read" ], "summary": "Get session connection history", "tags": [ "Sessions" ] } }, "/v1/recordings": { "get": { "operationId": "listRecordings", "description": "List this workspace's private recordings, newest first. Metadata uses stable recording IDs and retainedUntil; download URLs are issued separately.\n\nRequires an API key with the `recordings:read` scope.", "parameters": [ { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to one session." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The previous response's nextCursor." } ], "responses": { "200": { "description": "Recordings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRecordingsResponse" } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "recordings:read" ], "summary": "List session recordings", "tags": [ "Recordings" ] } }, "/v1/recordings/{recordingId}": { "get": { "operationId": "getRecording", "description": "Get durable metadata for an owned recording. Pending recordings reconcile with the recording provider. Retention expiry preserves metadata and blocks media access.\n\nRequires an API key with the `recordings:read` scope.", "parameters": [ { "name": "recordingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recording", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recording" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recording not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Recording status temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "recordings:read" ], "summary": "Get recording status", "tags": [ "Recordings" ] } }, "/v1/recordings/{recordingId}/access": { "get": { "operationId": "getRecordingAccess", "description": "Issue a signed GET URL for a ready recording. The URL supports byte ranges and defaults to one hour, capped by retainedUntil. Request a new URL with this API key when it expires; URL expiry does not delete media. Keep this URL private.\n\nRequires an API key with the `recordings:read` scope.", "parameters": [ { "name": "recordingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Temporary access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordingAccessResponse" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recording not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Recording not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Recording retention expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Recording media temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "recordings:read" ], "summary": "Get a temporary recording download URL", "tags": [ "Recordings" ] } }, "/v1/usage/sessions": { "get": { "operationId": "listUsageSessions", "description": "Per-second billable detail. The window defaults to the trailing 30 days and is CLAMPED to 90 — a wider range is served narrowed, not refused, so read back the returned from/to.\n\nRequires an API key with the `usage:read` scope.", "parameters": [ { "name": "X-RTA-Release-Evidence", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Send 1 to include optional session-bound releaseIdentity in this response. Without this opt-in the field is omitted for strict client compatibility. Capture and storage are independent of this header; missing evidence remains null. Older servers may ignore this header." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Start of the window. Defaults to 30 days before `to`; clamped to no earlier than 90 days before it." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "End of the window. Defaults to now." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows per page. Defaults to 50, clamped to 1–200." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor — pass the previous response's `nextCursor` verbatim. A null `nextCursor` means the last page." }, { "name": "endUserId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Narrow to one of YOUR users — matches the `client_metadata.user_id` the call was minted with. Untagged calls still return, with empty metadata." } ], "responses": { "200": { "description": "Sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsageSessionsResponse" } } } }, "401": { "description": "Missing, malformed, revoked, or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope for this operation, or the tenant is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads \"does not belong to this tenant\", which is a missing id and not a permission failure), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 500 (unhandled). Switch on `code` where present, else `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "usage:read" ], "summary": "List billed realtime sessions", "tags": [ "Usage" ] } } }, "x-clip-contract": { "source": "/character-motion.ts", "sha256": "d73d23691e9ad06215b23df390b7fd9985bab052bf43641f3324e4cc66662d20" }, "x-connection-history-contract": { "source": "/connection-history.contract.ts", "sha256": "29065e487f83c0f8345f9efb1962638ad639ce79ec1f81ed29cf083a1c881eae" }, "x-recording-contract": { "source": "/recording.contract.ts", "sha256": "02e18ab663879c38c620ba9ef911c6c3dd3c0ea554604abd4403d7b2185d0f9e" }, "tags": [ { "name": "API keys", "description": "Mint the keys that authenticate every other call." }, { "name": "Assets", "description": "Upload the portraits and audio an avatar is built from." }, { "name": "Avatars", "description": "Create a character, then change her clips and her resting loop by description." }, { "name": "Credits", "description": "What the workspace has left, and what live calls are holding." }, { "name": "Realtime", "description": "Mint, release and size the live calls themselves." }, { "name": "Recordings", "description": "Private session recordings and renewable access URLs." }, { "name": "Scenes", "description": "Preview, enabled per workspace: prepare a supplied clip once, then play it as a session's picture." }, { "name": "Sessions", "description": "Connection observations associated with your sessions." }, { "name": "Usage", "description": "Per-session billed detail, for reconciling against the invoice." } ] }