Start a realtime avatar session: the avatar joins the LiveKit room you name in transport, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that transport.publisher_identity streams to it over a LiveKit data stream. The response is the session object with status: "active"; the avatar is already in the room. Release it with DELETE /v1/avatar/sessions/{session_id} when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.
Rendered video size in pixels (portrait or square works best). Optional; defaults to 480x640. The reference image is center-cropped to this aspect ratio.
Hard cap on the session length; the session ends and the avatar leaves the room when it is reached. Optional; defaults to the account limit (3600 s), which a larger value may not exceed (invalid_duration).
Required range: 1 <= x <= 14400
Example:
1800
Response
The session is active and the avatar has joined the room.
A realtime avatar session (the create / retrieve / release response).
active: the avatar is in the room. releasing: a release was requested and is not confirmed yet. terminated: the session has ended (released, expired, room emptied, or ended by Boson for another reason).
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Boson","description":"Build with Higgs Realtime, Higgs TTS 3, and Higgs Avatar APIs.","colors":{"primary":"#17B726","light":"#3DD24A","dark":"#1D7028"},"logo":{"light":"https://mintcdn.com/bosonai/nle8KC3HRTUuBQvw/public/images/boson_ai_logo.svg?fit=max\u0026auto=format\u0026n=nle8KC3HRTUuBQvw\u0026q=85\u0026s=a612c3151ec7dfaae986ba9f8053392b","dark":"https://mintcdn.com/bosonai/nle8KC3HRTUuBQvw/public/images/logo_light.svg?fit=max\u0026auto=format\u0026n=nle8KC3HRTUuBQvw\u0026q=85\u0026s=2aa7370dbe21e0a611129de5bd0dd16d"},"favicon":"https://mintcdn.com/bosonai/nle8KC3HRTUuBQvw/public/images/favicon.ico?fit=max\u0026auto=format\u0026n=nle8KC3HRTUuBQvw\u0026q=85\u0026s=24cc72e718eee5ab1ef7451dd1624648","navbar":{"links":[{"href":"/feedback","label":"Feedback"}],"primary":{"type":"button","label":"Workspace","href":"https://www.boson.ai/workspace"}},"footer":{"socials":{"x":"https://x.com/boson_ai","github":"https://github.com/boson-ai"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"bosonai","hasAudioNarration":false,"actualSubdomain":"bosonai","customDomains":["docs.boson.ai"],"gitSource":{"type":"github","owner":"boson-ai","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6aeceeeb6615eaa1b7d4cca5","clientVersion":"0.0.4088","searchFilterCounts":[{"language":"default","tag":"Documentation","count":26},{"language":"default","tag":"API Reference","count":19},{"language":"default","tag":"Higgs Realtime","count":9},{"language":"default","tag":"Avatar Realtime API","count":5},{"language":"default","tag":"Get started","count":5},{"language":"default","tag":"Text-to-Speech API","count":5},{"language":"default","tag":"Realtime API","count":4},{"language":"default","tag":"Higgs Avatar","count":4},{"language":"default","tag":"Guides","count":4},{"language":"default","tag":"Higgs TTS 3","count":4}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","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":"llms-txt-v2","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":"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":"comment-mode","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"#sidebar [data-sidebar-group-title],#sidebar .sidebar-group-title,#sidebar [class*=\"GroupTitle\"],aside [data-sidebar-group-title],aside .sidebar-group-title,aside [class*=\"GroupTitle\"],nav[aria-label=\"Sidebar\"] li>h5,nav[aria-label=\"Sidebar\"] li>h4,nav[aria-label=\"Sidebar\"] li>div[class*=\"font-semibold\"]:first-child{font-size:0.7rem!important;font-weight:600!important;letter-spacing:0.08em!important;text-transform:uppercase!important;color:rgb(115, 115, 115)!important;margin-top:1.25rem!important;margin-bottom:0.5rem!important}html.dark #sidebar [data-sidebar-group-title],html.dark #sidebar .sidebar-group-title,html.dark #sidebar [class*=\"GroupTitle\"],html.dark aside [data-sidebar-group-title],html.dark aside .sidebar-group-title,html.dark aside [class*=\"GroupTitle\"],html.dark nav[aria-label=\"Sidebar\"] li>h5,html.dark nav[aria-label=\"Sidebar\"] li>h4,html.dark nav[aria-label=\"Sidebar\"] li>div[class*=\"font-semibold\"]:first-child{color:rgb(160, 160, 160)!important}main table th:not(:last-child),main table td:not(:last-child){white-space:nowrap;width:1%}main table th:last-child,main table td:last-child{width:auto;min-width:14rem;white-space:normal}main table th,main table td{vertical-align:middle!important}@media (max-width: 640px){main .expand-schema-container,main .expand-schema-container>div,main .expand-schema-container .border-none,main .expand-schema-container .font-mono.font-bold,main .expand-schema-container .text-xs.truncate{max-width:100%;min-width:0}}main .realtime-event-catalog>p,main .realtime-event-catalog>[data-as=\"p\"],main .realtime-event-catalog>ul,main .realtime-event-catalog>ol{font-size:0.875rem;line-height:1.5rem}main .realtime-event-catalog>h2{font-size:1.125rem;line-height:1.6875rem}main .realtime-event-catalog>h3{font-size:1rem;line-height:1.5rem}main .realtime-event-catalog table{font-size:0.8125rem;line-height:1.25rem;table-layout:auto;width:100%}main .realtime-event-catalog table th,main .realtime-event-catalog table td,main .realtime-event-catalog table th:not(:last-child),main .realtime-event-catalog table td:not(:last-child),main .realtime-event-catalog table th:last-child,main .realtime-event-catalog table td:last-child{min-width:0;white-space:normal;width:auto}main .realtime-event-catalog table code{overflow-wrap:anywhere;word-break:break-word}main .tags-sample-tables table{border-collapse:separate;border-spacing:0 0.75rem;display:block;width:100%}main .tags-sample-tables table thead{display:none}main .tags-sample-tables table tbody{display:grid;gap:0.75rem}main .tags-sample-tables table tr{border:1px solid rgb(229, 229, 229);border-radius:0.5rem;display:grid;gap:0.5rem 1rem;grid-template-columns:minmax(8rem, max-content) 1fr 14rem;padding:0.875rem 1rem}html.dark main .tags-sample-tables table tr{border-color:rgb(64, 64, 64)}main .tags-sample-tables table td{border:0!important;padding:0!important;white-space:normal!important;width:auto}main .tags-sample-tables table td::before{color:rgb(115, 115, 115);display:block;font-size:0.75rem;font-weight:600;margin-bottom:0.125rem}html.dark main .tags-sample-tables table td::before{color:rgb(160, 160, 160)}main .tags-sample-tables table td:nth-child(1)::before{content:\"Tag\"}main .tags-sample-tables table td:nth-child(1) code{background:rgb(237, 247, 237);border:1px solid rgb(188, 220, 188);color:rgb(29, 112, 40);font-weight:700}html.dark main .tags-sample-tables table td:nth-child(1) code{background:rgba(34, 197, 94, 0.12);border-color:rgba(34, 197, 94, 0.35);color:rgb(134, 239, 172)}main .tags-sample-tables table td:nth-child(2)::before{content:\"Effect\"}main .tags-sample-tables table td:nth-child(3)::before{content:\"Sample input\"}main .tags-sample-tables table td:nth-child(4)::before{content:\"Sample audio\"}main .tags-sample-tables table td:nth-child(2){grid-column:2 / -1}main .tags-sample-tables table td:nth-child(3){grid-column:1 / 3}main .tags-sample-tables table td:nth-child(4){grid-column:3 / 4;grid-row:2}main .tags-sample-tables table td:nth-child(3) code{display:inline;overflow-wrap:anywhere;word-break:break-word;white-space:normal}main .tags-sample-tables table audio{display:block;max-width:100%;width:14rem}main .voice-sample-tables table{border-collapse:separate;border-spacing:0 0.75rem;display:block;width:100%}main .voice-sample-tables table thead{display:none}main .voice-sample-tables table tbody{display:grid;gap:0.75rem}main .voice-sample-tables table tr{border:1px solid rgb(229, 229, 229);border-radius:0.5rem;display:grid;gap:0.5rem 1rem;grid-template-columns:minmax(6rem, max-content) 1fr 14rem;padding:0.875rem 1rem}html.dark main .voice-sample-tables table tr{border-color:rgb(64, 64, 64)}main .voice-sample-tables table td{border:0!important;padding:0!important;white-space:normal!important;width:auto}main .voice-sample-tables table td::before{color:rgb(115, 115, 115);display:block;font-size:0.75rem;font-weight:600;margin-bottom:0.125rem}html.dark main .voice-sample-tables table td::before{color:rgb(160, 160, 160)}main .voice-sample-tables table td:nth-child(1)::before{content:\"Voice\"}main .voice-sample-tables table td:nth-child(1) code{background:rgb(237, 247, 237);border:1px solid rgb(188, 220, 188);color:rgb(29, 112, 40);font-weight:700}html.dark main .voice-sample-tables table td:nth-child(1) code{background:rgba(34, 197, 94, 0.12);border-color:rgba(34, 197, 94, 0.35);color:rgb(134, 239, 172)}main .voice-sample-tables table td:nth-child(2)::before{content:\"Style\"}main .voice-sample-tables table td:nth-child(3)::before{content:\"Sample input\"}main .voice-sample-tables table td:nth-child(4)::before{content:\"Sample audio\"}main .voice-sample-tables table td:nth-child(2){grid-column:2 / -1}main .voice-sample-tables table td:nth-child(3){grid-column:1 / 3}main .voice-sample-tables table td:nth-child(4){grid-column:3 / 4;grid-row:2}main .voice-sample-tables table td:nth-child(3) code{display:inline;overflow-wrap:anywhere;word-break:break-word;white-space:normal}main .voice-sample-tables table audio{display:block;max-width:100%;width:14rem}main .fine-control-sample-table table{border-collapse:separate;border-spacing:0;display:block;width:100%}main .fine-control-sample-table table thead{display:none}main .fine-control-sample-table table tr{border:1px solid rgb(229, 229, 229);border-radius:0.5rem;display:grid;gap:0.5rem 1rem;grid-template-columns:1fr 14rem;padding:0.875rem 1rem}html.dark main .fine-control-sample-table table tr{border-color:rgb(64, 64, 64)}main .fine-control-sample-table table td{border:0!important;padding:0!important;white-space:normal!important;width:auto!important}main .fine-control-sample-table table td::before{color:rgb(115, 115, 115);display:block;font-size:0.75rem;font-weight:600;margin-bottom:0.125rem}html.dark main .fine-control-sample-table table td::before{color:rgb(160, 160, 160)}main .fine-control-sample-table table td:nth-child(1)::before{content:\"Sample input\"}main .fine-control-sample-table table td:nth-child(2)::before{content:\"Sample audio\"}main .fine-control-sample-table table td:nth-child(1) code{display:inline;overflow-wrap:anywhere;word-break:break-word;white-space:normal}main .fine-control-sample-table table audio{display:block;margin-top:0.35rem;max-width:100%;width:14rem}img[src*=\"boson_ai_logo\"],img[src*=\"logo_light\"]{height:1.5rem!important;max-height:1.5rem!important;width:auto!important}@media (max-width: 768px){main table{display:block;max-width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch}main table td:last-child,main table th:last-child{min-width:16rem}main .tags-sample-tables table tr{display:block;min-width:0;width:100%}main .tags-sample-tables table tbody,main .tags-sample-tables table td{display:block;min-width:0!important;width:100%!important}main .tags-sample-tables table td+td{margin-top:0.45rem}main .tags-sample-tables table audio{width:12rem}main .voice-sample-tables table tr{display:block;min-width:0;width:100%}main .voice-sample-tables table tbody,main .voice-sample-tables table td{display:block;min-width:0!important;width:100%!important}main .voice-sample-tables table td+td{margin-top:0.45rem}main .voice-sample-tables table audio{width:12rem}main .fine-control-sample-table table tr{display:block;min-width:0;width:100%}main .fine-control-sample-table table td{display:block;min-width:0!important;width:100%!important}main .fine-control-sample-table table td+td{margin-top:0.45rem}main .fine-control-sample-table table audio{width:12rem}}"}],"page":{"pagePath":"api-reference/avatar-realtime/create-a-session","slug":"/api-reference/avatar-realtime/create-a-session","pageMetadata":{"title":"Create a session","description":"Start a realtime avatar session: the avatar joins the LiveKit room you name in `transport`, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that `transport.publisher_identity` streams to it over a LiveKit data stream. The response is the session object with `status: \"active\"`; the avatar is already in the room. Release it with `DELETE /v1/avatar/sessions/{session_id}` when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/avatar/sessions","href":"/api-reference/avatar-realtime/create-a-session","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Start a realtime avatar session: the avatar joins the LiveKit room you name in \", _jsx(_components.code, {\n children: \"transport\"\n }), \", as the participant whose token you minted, and publishes lip-synced video together with the speech audio that \", _jsx(_components.code, {\n children: \"transport.publisher_identity\"\n }), \" streams to it over a LiveKit data stream. The response is the session object with \", _jsx(_components.code, {\n children: \"status: \\\"active\\\"\"\n }), \"; the avatar is already in the room. Release it with \", _jsx(_components.code, {\n children: \"DELETE /v1/avatar/sessions/{session_id}\"\n }), \" when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.\"]\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};\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 a session","description":"Start a realtime avatar session: the avatar joins the LiveKit room you name in `transport`, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that `transport.publisher_identity` streams to it over a LiveKit data stream. The response is the session object with `status: \"active\"`; the avatar is already in the room. Release it with `DELETE /v1/avatar/sessions/{session_id}` when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/avatar/sessions","href":"/api-reference/avatar-realtime/create-a-session","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"createAvatarSession","summary":"Create a session","description":"Start a realtime avatar session: the avatar joins the LiveKit room you name in `transport`, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that `transport.publisher_identity` streams to it over a LiveKit data stream. The response is the session object with `status: \"active\"`; the avatar is already in the room. Release it with `DELETE /v1/avatar/sessions/{session_id}` when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.","tags":["Avatar Realtime"],"requestBody":"38ab8d78-6ca8-4d57-8f10-b7f9616218c8","responses":{"201":"18aee2b6-3d01-4a91-b4de-3655df358e61","400":"2e98ad0e-2085-4c43-93ba-c413f63014e3","401":"f29b5238-97ef-43b2-80c2-fa4bd8248a8b","403":"aae806cf-e94a-42d8-bdd2-5d2198bd3e7b","404":"c49959e3-3fad-43bf-8018-d4e9355e420f","422":"b825c915-29ea-4296-affa-7aa329b498a6","429":"367004b7-5b2c-4e6b-b94c-e4549b490edf","503":"c9627490-ac53-4d68-8a40-cb8e001a6fea"},"method":"post","type":"path","servers":["38634cbe-d3ba-4b12-9186-b84b1c86958d"],"security":["aef5896e-44d4-4e68-82f6-37316621e7e0"],"path":"/v1/avatar/sessions","baseUrlOptions":["https://api.boson.ai"],"title":"Create a session","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["avatar_id","transport"],"properties":{"avatar_id":{"type":"string","minLength":1,"maxLength":256,"description":"The face to render: a preset or an avatar owned by this API key, from `GET /v1/avatars`.","example":"builtin_claire_v1","isRequired":true,"uniqueKey":"avatar_id","typeLabel":"string"},"transport":{"type":"object","description":"The LiveKit room the avatar joins. You own the room and mint the avatar's token with your LiveKit API key and secret.","required":["url","room_name","participant_token","participant_identity","publisher_identity"],"properties":{"url":{"type":"string","maxLength":2048,"description":"Your LiveKit Cloud project URL, `wss://\u003cproject>.livekit.cloud`.","example":"wss://my-project.livekit.cloud","isRequired":true,"uniqueKey":"transport.url","typeLabel":"string"},"room_name":{"type":"string","minLength":1,"maxLength":128,"description":"Name of the room the avatar joins. LiveKit Cloud creates the room when its first participant joins, so it needs no setup.","isRequired":true,"uniqueKey":"transport.room_name","typeLabel":"string"},"participant_token":{"type":"string","minLength":1,"maxLength":16384,"description":"LiveKit access token for the avatar participant, minted by you. Grants: `roomJoin` for `room_name`, `canPublish` with camera and microphone sources, and `canPublishData`. Its identity must equal `participant_identity`, and its TTL must outlast the session (`max_duration_seconds` plus a margin). The API does not inspect the token; a token with the wrong identity or grants fails when the avatar joins the room. This value is never echoed back or logged.","isRequired":true,"uniqueKey":"transport.participant_token","typeLabel":"string"},"participant_identity":{"type":"string","minLength":1,"maxLength":128,"description":"Identity the avatar joins as. Must differ from `publisher_identity`.","example":"boson-avatar-agent","isRequired":true,"uniqueKey":"transport.participant_identity","typeLabel":"string"},"publisher_identity":{"type":"string","minLength":1,"maxLength":128,"description":"Identity of the participant that streams the speech audio to the avatar (your voice agent). The avatar lip-syncs to this audio.","example":"agent-7f3a","isRequired":true,"uniqueKey":"transport.publisher_identity","typeLabel":"string"},"type":{"type":"string","enum":["livekit"],"default":"livekit","description":"Realtime provider. `livekit` is the only value today.","uniqueKey":"transport.type","typeLabel":"enum\u003cstring>"},"audio_source":{"type":"string","enum":["data_stream"],"default":"data_stream","description":"How the speech audio reaches the avatar. `data_stream`: the LiveKit Agents avatar audio protocol, a LiveKit byte stream of 16-bit PCM frames (24 kHz) from `publisher_identity` to `participant_identity`, as `DataStreamAudioOutput` in `livekit-agents` implements it, including its playback and clear-buffer RPCs. The avatar republishes this audio as its own audio track together with the video.","uniqueKey":"transport.audio_source","typeLabel":"enum\u003cstring>"}},"isRequired":true,"uniqueKey":"transport","typeLabel":"object"},"model":{"type":"string","default":"higgs-avatar","enum":["higgs-avatar"],"description":"Avatar model ID, the same ID as `POST /v1/videos` uses. Optional; defaults to `higgs-avatar`.","uniqueKey":"model","typeLabel":"enum\u003cstring>"},"output":{"type":"object","description":"Rendered video size in pixels (portrait or square works best). Optional; defaults to 480x640. The reference image is center-cropped to this aspect ratio.","required":["width","height"],"properties":{"width":{"type":"integer","minimum":64,"maximum":2048,"example":480,"isRequired":true,"uniqueKey":"output.width","typeLabel":"integer"},"height":{"type":"integer","minimum":64,"maximum":2048,"example":640,"isRequired":true,"uniqueKey":"output.height","typeLabel":"integer"}},"uniqueKey":"output","typeLabel":"object"},"max_duration_seconds":{"type":"integer","minimum":1,"maximum":14400,"description":"Hard cap on the session length; the session ends and the avatar leaves the room when it is reached. Optional; defaults to the account limit (3600 s), which a larger value may not exceed (`invalid_duration`).","example":1800,"uniqueKey":"max_duration_seconds","typeLabel":"integer"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"avatar_id":"builtin_claire_v1","transport":{"url":"wss://my-project.livekit.cloud","room_name":"\u003cstring>","participant_token":"\u003cstring>","participant_identity":"boson-avatar-agent","publisher_identity":"agent-7f3a","type":"livekit","audio_source":"data_stream"},"model":"higgs-avatar","max_duration_seconds":1800}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"18aee2b6-3d01-4a91-b4de-3655df358e61":{"description":"The session is active and the avatar has joined the room.","content":{"application/json":{"schema":{"type":"object","description":"A realtime avatar session (the create / retrieve / release response).","properties":{"id":{"type":"string","description":"Session ID, e.g. `avrt_...`.","example":"avrt_3f9c2a7e8b1d4c6f","uniqueKey":"id","typeLabel":"string"},"object":{"type":"string","enum":["avatar.realtime.session"],"default":"avatar.realtime.session","uniqueKey":"object","typeLabel":"enum\u003cstring>"},"status":{"type":"string","enum":["active","releasing","terminated"],"description":"`active`: the avatar is in the room. `releasing`: a release was requested and is not confirmed yet. `terminated`: the session has ended (released, expired, room emptied, or ended by Boson for another reason).","uniqueKey":"status","typeLabel":"enum\u003cstring>"},"model":{"type":"string","example":"higgs-avatar","uniqueKey":"model","typeLabel":"string"},"avatar_id":{"type":"string","example":"builtin_claire_v1","uniqueKey":"avatar_id","typeLabel":"string"},"avatar_identity":{"type":"string","description":"The LiveKit identity the avatar joined as (`transport.participant_identity`).","example":"boson-avatar-agent","uniqueKey":"avatar_identity","typeLabel":"string"},"created_at":{"type":"string","format":"date-time","description":"When the avatar joined the room (ISO 8601, UTC).","uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"expires_at":{"type":"string","format":"date-time","description":"Latest end time: the session ends at this time if it is still running (`created_at` + `max_duration_seconds`).","uniqueKey":"expires_at","typeLabel":"string\u003cdate-time>"},"ended_at":{"oneOf":[{"type":"string","format":"date-time","description":"When the session ended; `null` while it is active.","uniqueKey":"ended_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"When the session ended; `null` while it is active.","uniqueKey":"ended_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"ended_at","typeLabel":"string\u003cdate-time> | null"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"id":"avrt_3f9c2a7e8b1d4c6f","object":"avatar.realtime.session","status":"active","model":"higgs-avatar","avatar_id":"builtin_claire_v1","avatar_identity":"boson-avatar-agent","created_at":"2023-11-07T05:31:56Z","expires_at":"2023-11-07T05:31:56Z","ended_at":"2023-11-07T05:31:56Z"}}},"exampleType":"generated"}},"exampleType":"generated"},"2e98ad0e-2085-4c43-93ba-c413f63014e3":{"description":"Malformed body: a missing field (`missing_required_field`) or a value outside its bounds or an unknown field (`invalid_field_value`), e.g. a `transport.url` that does not start with `wss://`, `max_duration_seconds` over 14400, or an `output` side outside 64–2048.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"type":{"type":"string","description":"Error category.","uniqueKey":"error.type","typeLabel":"string"},"code":{"oneOf":[{"type":"string","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.0","typeLabel":"string"},{"type":"null","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.code","typeLabel":"string | null"},"param":{"oneOf":[{"type":"string","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.0","typeLabel":"string"},{"type":"null","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.param","typeLabel":"string | null"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"message":"\u003cstring>","type":"\u003cstring>","code":"\u003cstring>","param":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"f29b5238-97ef-43b2-80c2-fa4bd8248a8b":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"type":{"type":"string","description":"Error category.","uniqueKey":"error.type","typeLabel":"string"},"code":{"oneOf":[{"type":"string","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.0","typeLabel":"string"},{"type":"null","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.code","typeLabel":"string | null"},"param":{"oneOf":[{"type":"string","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.0","typeLabel":"string"},{"type":"null","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.param","typeLabel":"string | null"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"message":"\u003cstring>","type":"\u003cstring>","code":"\u003cstring>","param":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"aae806cf-e94a-42d8-bdd2-5d2198bd3e7b":{"description":"The API key may not use the requested `model`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"type":{"type":"string","description":"Error category.","uniqueKey":"error.type","typeLabel":"string"},"code":{"oneOf":[{"type":"string","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.0","typeLabel":"string"},{"type":"null","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.code","typeLabel":"string | null"},"param":{"oneOf":[{"type":"string","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.0","typeLabel":"string"},{"type":"null","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.param","typeLabel":"string | null"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"message":"\u003cstring>","type":"\u003cstring>","code":"\u003cstring>","param":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"c49959e3-3fad-43bf-8018-d4e9355e420f":{"description":"Unknown `model`, or one that does not serve realtime sessions (`model_not_found`); unknown `avatar_id` (`avatar_not_found`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"type":{"type":"string","description":"Error category.","uniqueKey":"error.type","typeLabel":"string"},"code":{"oneOf":[{"type":"string","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.0","typeLabel":"string"},{"type":"null","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.code","typeLabel":"string | null"},"param":{"oneOf":[{"type":"string","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.0","typeLabel":"string"},{"type":"null","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.param","typeLabel":"string | null"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"message":"\u003cstring>","type":"\u003cstring>","code":"\u003cstring>","param":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"b825c915-29ea-4296-affa-7aa329b498a6":{"description":"Well-formed but not startable: `invalid_livekit_url` (a `wss://` URL without a host or with credentials, or a host that is not an approved LiveKit server; LiveKit Cloud project URLs are approved, self-hosted servers are not), `invalid_identity` (`participant_identity` equals `publisher_identity`), `invalid_duration` (`max_duration_seconds` over the account limit), or `unsupported_output` (the requested size is not supported).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"type":{"type":"string","description":"Error category.","uniqueKey":"error.type","typeLabel":"string"},"code":{"oneOf":[{"type":"string","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.0","typeLabel":"string"},{"type":"null","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.code","typeLabel":"string | null"},"param":{"oneOf":[{"type":"string","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.0","typeLabel":"string"},{"type":"null","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.param","typeLabel":"string | null"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"message":"\u003cstring>","type":"\u003cstring>","code":"\u003cstring>","param":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"367004b7-5b2c-4e6b-b94c-e4549b490edf":{"description":"Rate limited (`type: rate_limit_error`, `code: rate_limit_exceeded`), billing refusal (`type: insufficient_quota`, not transient), or every avatar slot in use (`capacity_exhausted`, with a `Retry-After` header in seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"type":{"type":"string","description":"Error category.","uniqueKey":"error.type","typeLabel":"string"},"code":{"oneOf":[{"type":"string","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.0","typeLabel":"string"},{"type":"null","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.code","typeLabel":"string | null"},"param":{"oneOf":[{"type":"string","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.0","typeLabel":"string"},{"type":"null","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.param","typeLabel":"string | null"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"message":"\u003cstring>","type":"\u003cstring>","code":"\u003cstring>","param":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"c9627490-ac53-4d68-8a40-cb8e001a6fea":{"description":"Temporarily unavailable (`service_unavailable`, with `Retry-After`), or realtime avatar is not enabled on this server (`not_configured`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message.","uniqueKey":"error.message","typeLabel":"string"},"type":{"type":"string","description":"Error category.","uniqueKey":"error.type","typeLabel":"string"},"code":{"oneOf":[{"type":"string","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.0","typeLabel":"string"},{"type":"null","description":"Machine-readable cause within `type`.","uniqueKey":"error.code.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.code","typeLabel":"string | null"},"param":{"oneOf":[{"type":"string","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.0","typeLabel":"string"},{"type":"null","description":"The offending parameter, if any.","uniqueKey":"error.param.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.param","typeLabel":"string | null"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"message":"\u003cstring>","type":"\u003cstring>","code":"\u003cstring>","param":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"aef5896e-44d4-4e68-82f6-37316621e7e0":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your Boson API key, sent as `Authorization: Bearer $BOSON_API_KEY`.","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"38634cbe-d3ba-4b12-9186-b84b1c86958d":{"url":"https://api.boson.ai"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"Your Boson API key, sent as `Authorization: Bearer $BOSON_API_KEY`.","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Your Boson API key, sent as `Authorization: Bearer $BOSON_API_KEY`.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"openapi.json"},"subdomain":"bosonai","siteName":"Boson","title":"Create a session - Boson","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-23T19:21:48.861Z","originalFileLocation":"api-reference/avatar-realtime/create-a-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=\"Start a realtime avatar session: the avatar joins the LiveKit room you name in transport, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that transport.publisher_identity streams to it over a LiveKit data stream. The response is the session object with status: \u0026quot;active\u0026quot;; the avatar is already in the room. Release it with DELETE /v1/avatar/sessions/{session_id} when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Boson\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_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/bosonai/3o-utK_tG8ZQHECF/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/bosonai/3o-utK_tG8ZQHECF/_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/bosonai/3o-utK_tG8ZQHECF/_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/bosonai/3o-utK_tG8ZQHECF/_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/bosonai/3o-utK_tG8ZQHECF/_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/bosonai/3o-utK_tG8ZQHECF/_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/bosonai/3o-utK_tG8ZQHECF/_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/bosonai/3o-utK_tG8ZQHECF/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create a session - Boson\">\u003cmeta data-mint-head property=\"og:description\" content=\"Start a realtime avatar session: the avatar joins the LiveKit room you name in transport, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that transport.publisher_identity streams to it over a LiveKit data stream. The response is the session object with status: \u0026quot;active\u0026quot;; the avatar is already in the room. Release it with DELETE /v1/avatar/sessions/{session_id} when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Boson\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-session\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://bosonai.mintlify.site/_mintlify/api/og/v2?division=Avatar+Realtime+API\u0026amp;title=Create+a+session\u0026amp;description=Start+a+realtime+avatar+session%3A+the+avatar+joins+the+LiveKit+room+you+name+in+%60transport%60%2C+as+the+participant+whose+token+you+minted%2C+and+publishes+lip-synced+\u0026amp;theme=7f435c39c09c230ba761776a\u0026amp;signature=a987aaa3bba67badbb328c23d25c2c8eec9eb73d8f0fb106a233e871056fa427\">\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 a session - Boson\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Start a realtime avatar session: the avatar joins the LiveKit room you name in transport, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that transport.publisher_identity streams to it over a LiveKit data stream. The response is the session object with status: \u0026quot;active\u0026quot;; the avatar is already in the room. Release it with DELETE /v1/avatar/sessions/{session_id} when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://bosonai.mintlify.site/_mintlify/api/og/v2?division=Avatar+Realtime+API\u0026amp;title=Create+a+session\u0026amp;description=Start+a+realtime+avatar+session%3A+the+avatar+joins+the+LiveKit+room+you+name+in+%60transport%60%2C+as+the+participant+whose+token+you+minted%2C+and+publishes+lip-synced+\u0026amp;theme=7f435c39c09c230ba761776a\u0026amp;signature=a987aaa3bba67badbb328c23d25c2c8eec9eb73d8f0fb106a233e871056fa427\">\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/bosonai/3o-utK_tG8ZQHECF/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Boson\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#17B726\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-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/avatar-realtime/create-a-session.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.boson.ai/#organization\",\"name\":\"Boson\",\"url\":\"https://docs.boson.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/bosonai/nle8KC3HRTUuBQvw/public/images/boson_ai_logo.svg?fit=max\u0026auto=format\u0026n=nle8KC3HRTUuBQvw\u0026q=85\u0026s=a612c3151ec7dfaae986ba9f8053392b\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.boson.ai#website\",\"name\":\"Boson\",\"url\":\"https://docs.boson.ai\",\"publisher\":{\"@id\":\"https://docs.boson.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-session#webpage\",\"url\":\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-session\",\"name\":\"Create a session\",\"description\":\"Start a realtime avatar session: the avatar joins the LiveKit room you name in transport, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that transport.publisher_identity streams to it over a LiveKit data stream. The response is the session object with status: \\\"active\\\"; the avatar is already in the room. Release it with DELETE /v1/avatar/sessions/{session_id} when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.\",\"dateModified\":\"2026-10-23T19:21:48.861Z\",\"isPartOf\":{\"@id\":\"https://docs.boson.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-session#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-session#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Avatar Realtime API\",\"item\":\"https://docs.boson.ai/api-reference/avatar-realtime/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create a session\",\"item\":\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-session\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-session#apireference\",\"headline\":\"Create a session\",\"name\":\"Create a session\",\"description\":\"Start a realtime avatar session: the avatar joins the LiveKit room you name in transport, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that transport.publisher_identity streams to it over a LiveKit data stream. The response is the session object with status: \\\"active\\\"; the avatar is already in the room. Release it with DELETE /v1/avatar/sessions/{session_id} when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.\",\"url\":\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-session\",\"mainEntityOfPage\":{\"@id\":\"https://docs.boson.ai/api-reference/avatar-realtime/create-a-session#webpage\"},\"dateModified\":\"2026-10-23T19:21:48.861Z\",\"publisher\":{\"@id\":\"https://docs.boson.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.boson.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Boson\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Boson","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/overview"}]},{"tab":"API Reference","groups":[{"group":"Realtime API","pages":[{"title":"Overview","href":"/api-reference/realtime/overview"},{"title":"Create a client secret","openapi":"openapi.json POST /v1/realtime/client_secrets","playground":"simple","href":"/api-reference/realtime/client-secrets"},{"title":"Client events","asyncapi":"asyncapi.json clientEvents","href":"/api-reference/realtime/client-events"},{"title":"Server events","asyncapi":"asyncapi.json serverEvents","href":"/api-reference/realtime/server-events"}]},{"group":"Text-to-Speech API","pages":[{"title":"Create a speech","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/audio/speech","href":"/api-reference/audio/create-a-speech"},{"title":"Create a voice","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/audio/voices","href":"/api-reference/audio/create-a-voice"},{"title":"List voices","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/audio/voices","href":"/api-reference/audio/list-voices"},{"title":"Get a voice","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/audio/voices/{voice}","href":"/api-reference/audio/get-a-voice"},{"title":"Delete a voice","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/audio/voices/{voice}","href":"/api-reference/audio/delete-a-voice"}]},{"group":"Avatar API","pages":[{"title":"Create a video","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/videos","href":"/api-reference/videos/create-a-video"},{"title":"Retrieve a video","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/videos/{video_id}","href":"/api-reference/videos/retrieve-a-video"},{"title":"Download content","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/videos/{video_id}/content","href":"/api-reference/videos/download-content"},{"title":"Create a video (streaming)","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/videos/stream","href":"/api-reference/videos/create-a-video-streaming"}]},{"group":"Avatar Realtime API","pages":[{"title":"Overview","description":"Start, inspect and release realtime avatar sessions in your LiveKit rooms.","href":"/api-reference/avatar-realtime/overview"},{"title":"Create a session","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/avatar/sessions","href":"/api-reference/avatar-realtime/create-a-session"},{"title":"Retrieve a session","description":"Current state of a session. A session you did not create (with this API key) is reported as not found. Ended sessions stay retrievable until a few minutes after `expires_at`, then `404`.","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/avatar/sessions/{session_id}","href":"/api-reference/avatar-realtime/retrieve-a-session"},{"title":"Release a session","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/avatar/sessions/{session_id}","href":"/api-reference/avatar-realtime/release-a-session"},{"title":"List avatars","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/avatars","href":"/api-reference/avatar-realtime/list-avatars"}]},{"group":"Errors","pages":[{"title":"Common error types","href":"/api-reference/errors"}]}]}]},"basePath":"","title":"Create a session - Boson","buildId":"dpl_DTau1J5HqS9UTgVSDwGksstFWtPa","deploymentId":"dpl_DTau1J5HqS9UTgVSDwGksstFWtPa","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-5FCzAcfS.js","utils-SLtAG4EZ.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-2DZi8ZMu.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-D7J3nkzE.js","snippetPresets-D0Alv0AH.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-BI4qNJ2c.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-BD3uyr8j.js","shallow-D8iEBr5z.js","getApiPlaygroundDisplay-CgNP4lzR.js","CodeSnippet-CX-QHuMs.js","CodeSnippets-VlXE-ZUf.js","Page-D9ithiIZ.js","getPastedJson-DYNQkZ1M.js","icon-CzacdwOi.js","MethodPill-2JVqoYKi.js","DuplicateIcon-_xVXs-U8.js","createIcon-BRHrweLo.js","DynamicMarkdown-mQG_iQiE.js","SectionHeading-DMpJzv8f.js","axios-vUo_bRtp.js","Markdown-5FGIym-8.js","clsx-D-TRO5q5.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CdrJecqK.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-CHlcWBLM.js"]}