external — Avaturn Live opens a WebSocket to a URL you
provide and exchanges raw audio plus segment events with it.
The reference integration uses Pipecat;
see the open-source pipecat-avaturn-live-demo repo for a
working end-to-end example.
text-echo — legacy text-driven TTS playback.
Reach out to us if you want to integrate with something else.
Allows controlling what avatar says with text. The text is converted into audio using TTS engine.
Multiple TTS engines are supported.
TextEchoEngineConfig
OpenAIRealtimeAPICEConfig
CartesiaCEConfig
ExternalCEConfig
Show child attributes
background
enum<string>
default:default
Background type for the avatar. 'transparent' removes the background, 'default' uses the avatar's default background
Available options:
transparent,
default
model
enum<string>
default:delta
Available options:
delta,
golf
user_absent_timeout
integer
default:60
Seconds to wait before terminating the session if no user is connected
Required range: x >= 10
max_duration
integer
default:3600
Maximum session duration in seconds (max 24 hours)
Required range: 60 <= x <= 86400
Response
Successful Response
session_id
string
required
Session ID
token
string
required
Session token for Web SDK
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Avaturn.Live","colors":{"primary":"#000000","light":"#FFFFFF","dark":"#000000"},"logo":{"light":"https://mintcdn.com/avaturn-1492efa9/dllyramte2Auj8Ns/logo/light.svg?fit=max\u0026auto=format\u0026n=dllyramte2Auj8Ns\u0026q=85\u0026s=a9bbc776013d1747117044b4e175b621","dark":"https://mintcdn.com/avaturn-1492efa9/dllyramte2Auj8Ns/logo/dark.svg?fit=max\u0026auto=format\u0026n=dllyramte2Auj8Ns\u0026q=85\u0026s=291e7ba277d0172a89799a4ac7687723"},"favicon":"https://mintcdn.com/avaturn-1492efa9/dllyramte2Auj8Ns/favicon.svg?fit=max\u0026auto=format\u0026n=dllyramte2Auj8Ns\u0026q=85\u0026s=a573ab7fd5196fd351da26230737f585","navbar":{"links":[{"href":"mailto:support@avaturn.me","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://avaturn.live/dashboard"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"avaturn-1492efa9","hasAudioNarration":false,"actualSubdomain":"avaturn-1492efa9","customDomains":["docs.avaturn.live"],"gitSource":{"type":"github","owner":"avaturn","repo":"live-docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6ae921ad4f9c5e0fb2cf46e8:success","clientVersion":"0.0.4248","searchFilterCounts":[{"language":"default","tag":"Documentation","count":14},{"language":"default","tag":"API Reference","count":7},{"language":"default","tag":"Web SDK","count":4},{"language":"default","tag":"Conversation Engines","count":3},{"language":"default","tag":"Legacy","count":3},{"language":"default","tag":"SDK Reference","count":3},{"language":"default","tag":"Get Started","count":2},{"language":"default","tag":"REST API","count":2},{"language":"default","tag":"API Documentation","count":1}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"api-reference/create-session","slug":"/api-reference/create-session","pageMetadata":{"title":"Create Session","description":"Initiates a session.\n\n\u003cWarning>\n Call this endpoint from your backend.\n You must not expose your API Key in your frontend code.\n\u003c/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.","deprecated":null,"version":null,"openapi":"https://api.avaturn.live/api/v1/openapi.json post /api/v1/sessions","href":"/api-reference/create-session","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n li: \"li\",\n p: \"p\",\n ul: \"ul\",\n ..._provideComponents(),\n ...props.components\n }, {Warning} = _components;\n if (!Warning) _missingMdxReference(\"Warning\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Initiates a session.\"\n }), \"\\n\", _jsx(Warning, {\n children: _jsx(_components.p, {\n children: \"Call this endpoint from your backend.\\nYou must not expose your API Key in your frontend code.\"\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"Upon successful creation, the API returns a session token that can be safely used in Web SDK.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"There are a few ways to process what a user says and what avatar says.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"It’s configured via the conversation engine. Supported types:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"openai-realtime\"\n }), \" — Avaturn Live talks directly to OpenAI\\nRealtime on your behalf.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"cartesia\"\n }), \" — \", _jsx(_components.a, {\n href: \"https://docs.cartesia.ai/line/integrations/calls-api\",\n children: \"Cartesia Line\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"external\"\n }), \" — Avaturn Live opens a WebSocket to a URL you\\nprovide and exchanges raw audio plus segment events with it.\\nThe reference integration uses \", _jsx(_components.a, {\n href: \"https://docs.pipecat.ai\",\n children: \"Pipecat\"\n }), \";\\nsee the open-source \", _jsx(_components.code, {\n children: \"pipecat-avaturn-live-demo\"\n }), \" repo for a\\nworking end-to-end example.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"text-echo\"\n }), \" — legacy text-driven TTS playback.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Reach out to us if you want to integrate with something else.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Create Session","description":"Initiates a session.\n\n\u003cWarning>\n Call this endpoint from your backend.\n You must not expose your API Key in your frontend code.\n\u003c/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.","deprecated":null,"version":null,"openapi":"https://api.avaturn.live/api/v1/openapi.json post /api/v1/sessions","href":"/api-reference/create-session","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"summary":"Create Session","description":"Initiates a session.\n\n\u003cWarning>\n Call this endpoint from your backend.\n You must not expose your API Key in your frontend code.\n\u003c/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":"83a6e35f-4d82-4462-8f17-5bc961df1342","responses":{"200":"1a737bc5-a1e8-4c76-ae21-cd057f5e527c","422":"097e506d-45eb-4d6e-8ce9-2fbe224f49b1"},"security":["fa0b472f-8844-4f3f-86d4-0f0cc10262fe"],"method":"post","type":"path","servers":["6263e784-c0c3-4d1c-b2f8-3ad301af8f94"],"path":"/api/v1/sessions","baseUrlOptions":["https://api.avaturn.live"],"title":"Create Session","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"content":{"application/json":{"schema":{"properties":{"avatar_id":{"type":"string","title":"Avatar Id","description":"Avatar ID","default":"jane_20240829","uniqueKey":"avatar_id","typeLabel":"string"},"conversation_engine":{"oneOf":[{"type":"object","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.","required":["tts"],"properties":{"tts":{"properties":{"voice_id":{"type":"string","title":"Voice Id","description":"ID of the voice from the dashboard","isRequired":true,"uniqueKey":"conversation_engine.oneOf.0.tts.voice_id","typeLabel":"string"},"engine":{"type":"string","const":"elevenlabs","title":"Engine","default":"elevenlabs","uniqueKey":"conversation_engine.oneOf.0.tts.engine","typeLabel":"string"}},"type":"object","required":["voice_id"],"title":"TTSConfig","description":"Configures text-to-speech synthesis.","isRequired":true,"uniqueKey":"conversation_engine.oneOf.0.tts","typeLabel":"TTSConfig · object"},"type":{"type":"string","const":"text-echo","title":"Type","default":"text-echo","uniqueKey":"conversation_engine.oneOf.0.type","typeLabel":"string"}},"uniqueKey":"conversation_engine.oneOf.0","typeLabel":"TextEchoEngineConfig · object"},{"type":"object","title":"OpenAIRealtimeAPICEConfig","description":"Configures how avatar listens and responds","properties":{"type":{"type":"string","const":"openai-realtime","title":"Type","default":"openai-realtime","uniqueKey":"conversation_engine.oneOf.1.type","typeLabel":"string"},"client_secret":{"oneOf":[{"type":"string","title":"Client Secret","uniqueKey":"conversation_engine.oneOf.1.client_secret.oneOf.0","typeLabel":"string"},{"type":"null","title":"Client Secret","uniqueKey":"conversation_engine.oneOf.1.client_secret.oneOf.1","typeLabel":"null"}],"uniqueKey":"conversation_engine.oneOf.1.client_secret","typeLabel":"string | null"}},"uniqueKey":"conversation_engine.oneOf.1","typeLabel":"OpenAIRealtimeAPICEConfig · object"},{"type":"object","title":"CartesiaCEConfig","description":"Configures how avatar listens and responds","required":["access_token","agent_id"],"properties":{"access_token":{"type":"string","title":"Access Token","isRequired":true,"uniqueKey":"conversation_engine.oneOf.2.access_token","typeLabel":"string"},"agent_id":{"type":"string","title":"Agent Id","isRequired":true,"uniqueKey":"conversation_engine.oneOf.2.agent_id","typeLabel":"string"},"type":{"type":"string","const":"cartesia","title":"Type","default":"cartesia","uniqueKey":"conversation_engine.oneOf.2.type","typeLabel":"string"}},"uniqueKey":"conversation_engine.oneOf.2","typeLabel":"CartesiaCEConfig · object"},{"type":"object","title":"ExternalCEConfig","description":"Configures how avatar listens and responds","required":["url"],"properties":{"url":{"type":"string","title":"Url","description":"WebSocket URL Avaturn Live opens to your conversation engine. Use a `wss://` URL in production.","isRequired":true,"uniqueKey":"conversation_engine.oneOf.3.url","typeLabel":"string"},"type":{"type":"string","const":"external","title":"Type","default":"external","uniqueKey":"conversation_engine.oneOf.3.type","typeLabel":"string"},"audio":{"properties":{"user":{"properties":{"sample_rate":{"type":"integer","enum":[16000,24000],"title":"Sample Rate","default":24000,"uniqueKey":"conversation_engine.oneOf.3.audio.user.sample_rate","typeLabel":"enum\u003cinteger>"}},"type":"object","title":"ExternalAudioUserConfig","uniqueKey":"conversation_engine.oneOf.3.audio.user","typeLabel":"ExternalAudioUserConfig · object"}},"type":"object","title":"ExternalAudioConfig","uniqueKey":"conversation_engine.oneOf.3.audio","typeLabel":"ExternalAudioConfig · object"},"headers":{"oneOf":[{"type":"object","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 \u003ctoken>\"}.","additionalProperties":{"type":"string","uniqueKey":"conversation_engine.oneOf.3.headers.oneOf.0.additionalProperties","typeLabel":"string"},"uniqueKey":"conversation_engine.oneOf.3.headers.oneOf.0","typeLabel":"Headers · 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 \u003ctoken>\"}.","uniqueKey":"conversation_engine.oneOf.3.headers.oneOf.1","typeLabel":"null"}],"uniqueKey":"conversation_engine.oneOf.3.headers","typeLabel":"Headers · object | null"}},"uniqueKey":"conversation_engine.oneOf.3","typeLabel":"ExternalCEConfig · object"},{"type":"null","title":"Conversation Engine","description":"Configures how avatar listens and responds","uniqueKey":"conversation_engine.oneOf.4","typeLabel":"null"}],"uniqueKey":"conversation_engine","typeLabel":"TextEchoEngineConfig · object | OpenAIRealtimeAPICEConfig · object | CartesiaCEConfig · object | ExternalCEConfig · object | null"},"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","uniqueKey":"background","typeLabel":"enum\u003cstring>"},"model":{"type":"string","enum":["delta","golf"],"title":"Model","default":"delta","uniqueKey":"model","typeLabel":"enum\u003cstring>"},"user_absent_timeout":{"type":"integer","minimum":10,"title":"User Absent Timeout","description":"Seconds to wait before terminating the session if no user is connected","default":60,"uniqueKey":"user_absent_timeout","typeLabel":"integer"},"max_duration":{"type":"integer","maximum":86400,"minimum":60,"title":"Max Duration","description":"Maximum session duration in seconds (max 24 hours)","default":3600,"uniqueKey":"max_duration","typeLabel":"integer"}},"additionalProperties":true,"type":"object","title":"CreateSessionConfig","default":{"avatar_id":"jane_20240829","background":"default","model":"delta","user_absent_timeout":60,"max_duration":3600},"uniqueKey":"","typeLabel":"CreateSessionConfig · object"},"examples":{"text-echo-elevenlabs":{"title":"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":"\u003cvoice-id-here>"}},"background":"default","model":"delta","user_absent_timeout":60,"max_duration":3600}},"external-pipecat":{"title":"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 \u003cyour-shared-secret>"}},"background":"default","model":"delta","user_absent_timeout":60,"max_duration":3600}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"1a737bc5-a1e8-4c76-ae21-cd057f5e527c":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Session ID","isRequired":true,"uniqueKey":"session_id","typeLabel":"string"},"token":{"type":"string","title":"Token","description":"Session token for Web SDK","isRequired":true,"uniqueKey":"token","typeLabel":"string"}},"type":"object","required":["session_id","token"],"title":"CreateSessionResponse","uniqueKey":"","typeLabel":"CreateSessionResponse · object"},"examples":{"Example":{"title":"Example","value":{"session_id":"\u003cstring>","token":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"097e506d-45eb-4d6e-8ce9-2fbe224f49b1":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"oneOf":[{"type":"string","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.0","typeLabel":"string"},{"type":"integer","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.1","typeLabel":"integer"}],"uniqueKey":"detail.items.[INDEX].loc.items.[INDEX]","typeLabel":"string | integer"},"type":"array","title":"Location","isRequired":true,"uniqueKey":"detail.items.[INDEX].loc","typeLabel":"(string | integer)[]"},"msg":{"type":"string","title":"Message","isRequired":true,"uniqueKey":"detail.items.[INDEX].msg","typeLabel":"string"},"type":{"type":"string","title":"Error Type","isRequired":true,"uniqueKey":"detail.items.[INDEX].type","typeLabel":"string"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError","uniqueKey":"detail.items.[INDEX]","typeLabel":"ValidationError · object"},"type":"array","title":"Detail","uniqueKey":"detail","typeLabel":"ValidationError · object[]"}},"type":"object","title":"HTTPValidationError","uniqueKey":"","typeLabel":"HTTPValidationError · object"},"examples":{"Example":{"title":"Example","value":{"detail":[{"loc":["\u003cstring>"],"msg":"\u003cstring>","type":"\u003cstring>"}]}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"fa0b472f-8844-4f3f-86d4-0f0cc10262fe":{"HTTPBearer":{"type":"http","description":"avaturn.live API key","scheme":"bearer","scopes":[]}}},"servers":{"6263e784-c0c3-4d1c-b2f8-3ad301af8f94":{"url":"https://api.avaturn.live"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","description":"avaturn.live API key","scheme":"bearer","scopes":[]},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"avaturn.live API key","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"HTTPBearer","name":"Authorization"}],"title":"HTTPBearer"}]},"originalFileLocation":"https://api.avaturn.live/api/v1/openapi.json"},"subdomain":"avaturn-1492efa9","siteName":"Avaturn.Live","title":"Create Session - Avaturn.Live","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-05-25T23:13:34.528Z","originalFileLocation":"api-reference/create-session.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Initiates a session. Call this endpoint from your backend. You must not expose your API Key in your frontend code. Upon successful creation, the API returns a session token that can be safely used in Web SDK. There are a few ways to process what a user says and what avatar says. It\u0026#x27;s configured via the conversation engine. Supported types: - openai-realtime — Avaturn Live talks directly to OpenAI Realtime on your behalf. - cartesia — Cartesia Line - external — Avaturn Live opens a WebSocket to a URL you provide and exchanges raw audio plus segment events with it. The reference integration uses Pipecat; see the open-source pipecat-avaturn-live-demo repo for a working end-to-end example. - text-echo — legacy text-driven TTS playback. Reach out to us if you want to integrate with something else.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Avaturn.Live\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create Session - Avaturn.Live\">\u003cmeta data-mint-head property=\"og:description\" content=\"Initiates a session. Call this endpoint from your backend. You must not expose your API Key in your frontend code. Upon successful creation, the API returns a session token that can be safely used in Web SDK. There are a few ways to process what a user says and what avatar says. It\u0026#x27;s configured via the conversation engine. Supported types: - openai-realtime — Avaturn Live talks directly to OpenAI Realtime on your behalf. - cartesia — Cartesia Line - external — Avaturn Live opens a WebSocket to a URL you provide and exchanges raw audio plus segment events with it. The reference integration uses Pipecat; see the open-source pipecat-avaturn-live-demo repo for a working end-to-end example. - text-echo — legacy text-driven TTS playback. Reach out to us if you want to integrate with something else.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Avaturn.Live\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.avaturn.live/api-reference/create-session\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://avaturn-1492efa9.mintlify.site/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Create+Session\u0026amp;description=Initiates+a+session.%0A%0A%3CWarning%3E%0A++Call+this+endpoint+from+your+backend.%0A++You+must+not+expose+your+API+Key+in+your+frontend+code.%0A%3C%2FWarning%3E%0A%0AUpon+successful+cr\u0026amp;theme=ea7c6e14d76874fce2215a5e\u0026amp;signature=8ba62b558fdc09502b46342d7ffd3cdd9c734eed511963328d8f7ce1bc4273db\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create Session - Avaturn.Live\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Initiates a session. Call this endpoint from your backend. You must not expose your API Key in your frontend code. Upon successful creation, the API returns a session token that can be safely used in Web SDK. There are a few ways to process what a user says and what avatar says. It\u0026#x27;s configured via the conversation engine. Supported types: - openai-realtime — Avaturn Live talks directly to OpenAI Realtime on your behalf. - cartesia — Cartesia Line - external — Avaturn Live opens a WebSocket to a URL you provide and exchanges raw audio plus segment events with it. The reference integration uses Pipecat; see the open-source pipecat-avaturn-live-demo repo for a working end-to-end example. - text-echo — legacy text-driven TTS playback. Reach out to us if you want to integrate with something else.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://avaturn-1492efa9.mintlify.site/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Create+Session\u0026amp;description=Initiates+a+session.%0A%0A%3CWarning%3E%0A++Call+this+endpoint+from+your+backend.%0A++You+must+not+expose+your+API+Key+in+your+frontend+code.%0A%3C%2FWarning%3E%0A%0AUpon+successful+cr\u0026amp;theme=ea7c6e14d76874fce2215a5e\u0026amp;signature=8ba62b558fdc09502b46342d7ffd3cdd9c734eed511963328d8f7ce1bc4273db\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/avaturn-1492efa9/FcHXCbxsBdoQ8sQ6/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Avaturn.Live\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#000000\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.avaturn.live/api-reference/create-session\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/create-session.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.avaturn.live/#organization\",\"name\":\"Avaturn.Live\",\"url\":\"https://docs.avaturn.live\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/avaturn-1492efa9/dllyramte2Auj8Ns/logo/light.svg?fit=max\u0026auto=format\u0026n=dllyramte2Auj8Ns\u0026q=85\u0026s=a9bbc776013d1747117044b4e175b621\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.avaturn.live#website\",\"name\":\"Avaturn.Live\",\"url\":\"https://docs.avaturn.live\",\"publisher\":{\"@id\":\"https://docs.avaturn.live/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.avaturn.live/api-reference/create-session#webpage\",\"url\":\"https://docs.avaturn.live/api-reference/create-session\",\"name\":\"Create Session\",\"description\":\"Initiates a session. Call this endpoint from your backend. You must not expose your API Key in your frontend code. Upon successful creation, the API returns a session token that can be safely used in Web SDK. There are a few ways to process what a user says and what avatar says. It's configured via the conversation engine. Supported types: - openai-realtime — Avaturn Live talks directly to OpenAI Realtime on your behalf. - cartesia — Cartesia Line - external — Avaturn Live opens a WebSocket to a URL you provide and exchanges raw audio plus segment events with it. The reference integration uses Pipecat; see the open-source pipecat-avaturn-live-demo repo for a working end-to-end example. - text-echo — legacy text-driven TTS playback. Reach out to us if you want to integrate with something else.\",\"dateModified\":\"2026-05-25T23:13:34.528Z\",\"isPartOf\":{\"@id\":\"https://docs.avaturn.live#website\"},\"breadcrumb\":{\"@id\":\"https://docs.avaturn.live/api-reference/create-session#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.avaturn.live/api-reference/create-session#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Avaturn.Live\",\"item\":\"https://docs.avaturn.live\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create Session\",\"item\":\"https://docs.avaturn.live/api-reference/create-session\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.avaturn.live/api-reference/create-session#apireference\",\"headline\":\"Create Session\",\"name\":\"Create Session\",\"description\":\"Initiates a session. Call this endpoint from your backend. You must not expose your API Key in your frontend code. Upon successful creation, the API returns a session token that can be safely used in Web SDK. There are a few ways to process what a user says and what avatar says. It's configured via the conversation engine. Supported types: - openai-realtime — Avaturn Live talks directly to OpenAI Realtime on your behalf. - cartesia — Cartesia Line - external — Avaturn Live opens a WebSocket to a URL you provide and exchanges raw audio plus segment events with it. The reference integration uses Pipecat; see the open-source pipecat-avaturn-live-demo repo for a working end-to-end example. - text-echo — legacy text-driven TTS playback. Reach out to us if you want to integrate with something else.\",\"url\":\"https://docs.avaturn.live/api-reference/create-session\",\"mainEntityOfPage\":{\"@id\":\"https://docs.avaturn.live/api-reference/create-session#webpage\"},\"dateModified\":\"2026-05-25T23:13:34.528Z\",\"publisher\":{\"@id\":\"https://docs.avaturn.live/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.avaturn.live#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Avaturn.Live\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Avaturn.Live\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/create-session.md","siteName":"Avaturn.Live","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/introduction"}]},{"tab":"API Reference","groups":[{"group":"API Documentation","pages":[{"title":"API Reference","description":"Create, manage, and terminate avatar sessions from your backend.","href":"/api-reference/introduction"}]},{"group":"API Reference","pages":[{"title":"Create Session","deprecated":null,"version":null,"openapi":"https://api.avaturn.live/api/v1/openapi.json post /api/v1/sessions","href":"/api-reference/create-session"},{"title":"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.","deprecated":null,"version":null,"openapi":"https://api.avaturn.live/api/v1/openapi.json post /api/v1/sessions/{id}/tasks","href":"/api-reference/create-speech-task"},{"title":"Terminate Session","deprecated":null,"version":null,"openapi":"https://api.avaturn.live/api/v1/openapi.json delete /api/v1/sessions/{id}","href":"/api-reference/terminate-session"}]}]}]},"basePath":"","title":"Create Session - Avaturn.Live","deploymentId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","buildId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-BtG4DSkw.js","snippetPresets-C1k1xDhp.js","utils-PMJoEt4Y.js","style-to-object-BY3JEAdk.js","utils-DW3Pr7Jq.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-DIISLO2w.js","conditional-requirements-CFM0id0Q.js","cloneDeep-BErNCZCm.js","_Uint8Array-f0PCu9f_.js","isObject-FP1Yky1u.js","ApiExamples-OjY-8mqu.js","usePlaygroundInputsStore-B2HS2hUb.js","shallow-DVFuuIDQ.js","isEqual-DG0UKiQC.js","CodeSnippets-Cy6FBgwN.js","CodeSnippet-D1PtG8ed.js","getApiPlaygroundDisplay-Dkx2eNtL.js","Page-C8Cg25if.js","DynamicMarkdown-BvJIe00T.js","SectionHeading-B0rKYV8d.js","icon-yclzBff4.js","MethodPill-DxA11cCF.js","getPastedJson-CpkIDpMk.js","DuplicateIcon-CFCQNJ-D.js","axios-CsQoIw0U.js","Markdown-CK5C-fmV.js","AssistantPageLink-Cw134Dd-.js","dist-3xM3Qrc7.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}