{"openapi":"3.1.0","info":{"title":"API","version":"0.1.0"},"servers":[{"url":"https://api.avaturn.live"}],"paths":{"/api/v1/sessions":{"post":{"summary":"Create Session","description":"Initiates a session.\n\n<Warning>\n  Call this endpoint from your backend.\n  You must not expose your API Key in your frontend code.\n</Warning>\n\nUpon successful creation, the API returns a session token that can be safely used in Web SDK.\n\nThere are a few ways to process what a user says and what avatar says.\n\nIt's configured via the conversation engine. Supported types:\n\n- `openai-realtime` — Avaturn Live talks directly to OpenAI\n  Realtime on your behalf.\n- `cartesia` — [Cartesia Line](https://docs.cartesia.ai/line/integrations/calls-api)\n- `external` — Avaturn Live opens a WebSocket to a URL you\n  provide and exchanges raw audio plus segment events with it.\n  The reference integration uses [Pipecat](https://docs.pipecat.ai);\n  see the open-source `pipecat-avaturn-live-demo` repo for a\n  working end-to-end example.\n- `text-echo` — legacy text-driven TTS playback.\n\nReach out to us if you want to integrate with something else.","operationId":"post_create_session_api_v1_sessions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionConfig","default":{"avatar_id":"jane_20240829","background":"default","model":"delta","user_absent_timeout":60,"max_duration":3600}},"examples":{"text-echo-elevenlabs":{"summary":"Text-Echo engine with elevenlabs TTS","description":"Example shows default background. To use transparent background, set background='transparent'","value":{"avatar_id":"jane_20240829","conversation_engine":{"type":"text-echo","tts":{"engine":"elevenlabs","voice_id":"<voice-id-here>"}},"background":"default","model":"delta","user_absent_timeout":60,"max_duration":3600}},"external-pipecat":{"summary":"External conversation engine (Pipecat over WebSocket)","description":"Points Avaturn Live at a Pipecat agent reachable at wss://your-engine.example.com/avaturn-live/ws. Headers are forwarded on the WS upgrade so your engine can authenticate the connection.","value":{"avatar_id":"jane_20240829","conversation_engine":{"type":"external","url":"wss://your-engine.example.com/avaturn-live/ws","audio":{"user":{"sample_rate":24000}},"headers":{"Authorization":"Bearer <your-shared-secret>"}},"background":"default","model":"delta","user_absent_timeout":60,"max_duration":3600}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/sessions/{id}/tasks":{"post":{"summary":"Create Speech Task","description":"Adds the text to the avatar speech queue.\nIf the avatar is already speaking, the text fragment is queued to be spoken at a later time.\nNothing is said until you connect or while you're disconnected.","operationId":"append_text_api_v1_sessions__id__tasks_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"id","description":"Session ID"},"description":"Session ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_append_text_api_v1_sessions__id__tasks_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionSayResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sessions/{id}":{"delete":{"summary":"Terminate Session","description":"Terminates the session.\nIf the avatar is still talking, it kills the session anyway.","operationId":"delete_session_api_v1_sessions__id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"id","description":"Session ID"},"description":"Session ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_append_text_api_v1_sessions__id__tasks_post":{"properties":{"text":{"type":"string","title":"Text","description":"Text to say"}},"type":"object","required":["text"],"title":"Body_append_text_api_v1_sessions__id__tasks_post"},"CartesiaConversationEngineConfig":{"properties":{"type":{"type":"string","const":"cartesia","title":"Type","default":"cartesia"},"access_token":{"type":"string","title":"Access Token"},"agent_id":{"type":"string","title":"Agent Id"}},"type":"object","required":["access_token","agent_id"],"title":"CartesiaCEConfig"},"CreateSessionConfig":{"properties":{"avatar_id":{"type":"string","title":"Avatar Id","description":"Avatar ID","default":"jane_20240829"},"conversation_engine":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/TextEchoConversationEngineConfig"},{"$ref":"#/components/schemas/OpenAIRealtimeAPIConversationEngineConfig"},{"$ref":"#/components/schemas/CartesiaConversationEngineConfig"},{"$ref":"#/components/schemas/ExternalConversationEngineConfig"},{"$ref":"#/components/schemas/LiveKitConversationEngineConfig"}],"discriminator":{"propertyName":"type","mapping":{"cartesia":"#/components/schemas/CartesiaConversationEngineConfig","external":"#/components/schemas/ExternalConversationEngineConfig","livekit":"#/components/schemas/LiveKitConversationEngineConfig","openai-realtime":"#/components/schemas/OpenAIRealtimeAPIConversationEngineConfig","text-echo":"#/components/schemas/TextEchoConversationEngineConfig"}}},{"type":"null"}],"title":"Conversation Engine","description":"Configures how avatar listens and responds"},"background":{"type":"string","enum":["transparent","default"],"title":"Background","description":"Background type for the avatar. 'transparent' removes the background, 'default' uses the avatar's default background","default":"default"},"model":{"type":"string","enum":["delta","golf"],"title":"Model","default":"delta"},"user_absent_timeout":{"type":"integer","minimum":10.0,"title":"User Absent Timeout","description":"Seconds to wait before terminating the session if no user is connected","default":60},"max_duration":{"type":"integer","maximum":86400.0,"minimum":60.0,"title":"Max Duration","description":"Maximum session duration in seconds (max 24 hours)","default":3600}},"additionalProperties":true,"type":"object","title":"CreateSessionConfig"},"CreateSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Session ID"},"token":{"type":"string","title":"Token","description":"Session token for Web SDK"}},"type":"object","required":["session_id","token"],"title":"CreateSessionResponse"},"ExternalAudioConfig":{"properties":{"user":{"$ref":"#/components/schemas/ExternalAudioUserConfig"}},"type":"object","title":"ExternalAudioConfig"},"ExternalAudioUserConfig":{"properties":{"sample_rate":{"type":"integer","enum":[16000,24000],"title":"Sample Rate","default":24000}},"type":"object","title":"ExternalAudioUserConfig"},"ExternalConversationEngineConfig":{"properties":{"type":{"type":"string","const":"external","title":"Type","default":"external"},"url":{"type":"string","title":"Url","description":"WebSocket URL Avaturn Live opens to your conversation engine. Use a `wss://` URL in production."},"audio":{"$ref":"#/components/schemas/ExternalAudioConfig"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers","description":"Optional headers Avaturn Live forwards on the WebSocket upgrade request. Use this to authenticate the upgrade against your engine, e.g. {\"Authorization\": \"Bearer <token>\"}."}},"type":"object","required":["url"],"title":"ExternalCEConfig"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LiveKitConversationEngineConfig":{"properties":{"type":{"type":"string","const":"livekit","title":"Type","default":"livekit"},"url":{"type":"string","title":"Url"},"token":{"type":"string","title":"Token"},"agent_identity":{"type":"string","title":"Agent Identity"}},"type":"object","required":["url","token","agent_identity"],"title":"LiveKitCEConfig","description":"LiveKit-Agents-based conversation engine.\n\nCollapses transport + CE into a single worklet (``LiveKitWorklet``): the\nagent runs in a LiveKit room and we both publish avatar AV and consume\nagent TTS audio over the same room. The caller supplies ``url`` and a\npre-minted avatar join token."},"OpenAIRealtimeAPIConversationEngineConfig":{"properties":{"type":{"type":"string","const":"openai-realtime","title":"Type","default":"openai-realtime"},"client_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Secret"}},"type":"object","title":"OpenAIRealtimeAPICEConfig"},"SessionSayResponse":{"properties":{"task_id":{"type":"string","title":"Task Id","description":"Speech task ID"}},"type":"object","required":["task_id"],"title":"SessionSayResponse"},"TTSConfig":{"properties":{"engine":{"type":"string","const":"elevenlabs","title":"Engine","default":"elevenlabs"},"voice_id":{"type":"string","title":"Voice Id","description":"ID of the voice from the dashboard"}},"type":"object","required":["voice_id"],"title":"TTSConfig","description":"Configures text-to-speech synthesis."},"TextEchoConversationEngineConfig":{"properties":{"type":{"type":"string","const":"text-echo","title":"Type","default":"text-echo"},"tts":{"$ref":"#/components/schemas/TTSConfig"}},"type":"object","required":["tts"],"title":"TextEchoEngineConfig","description":"Text-based echo conversation engine.\n\nAllows controlling what avatar says with text. The text is converted into audio using TTS engine.\nMultiple TTS engines are supported."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"avaturn.live API key","scheme":"bearer"}}}}