--- updatedAt: 2026-09-14T17:11:04.000Z agentTools: projectIndex: https://docs.synthesia.io/llms.txt --- # Start an interactive avatar session Start an interactive avatar session. - Each running session counts toward your plan's concurrent-session limit until it ends. - Only sessions started through this API count toward the limit. - Over the limit, the request fails with `429` and code `concurrency_limit`; its `detail` states your plan's limit and how many sessions are running. | Plan | Concurrent sessions | | --- | --- | | Freemium | 1 | | All paid plans | 100 | **Required scope:** [`interactive_avatars:write`](https://developers.synthesia.io/docs/scopes) (in Studio: Interactive Avatars (write)) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Synthesia Public API", "version": "1.0.0", "description": "Synthesia's public developer API.\n\n- Authenticate every request with your API key: `Authorization: Bearer `. Some endpoints additionally require the key to carry a specific scope, named in the endpoint's description; [Scopes](https://developers.synthesia.io/docs/scopes) lists them all.\n- Errors are RFC 9457 Problem Details (`application/problem+json`): branch on the stable `code` field, never parse `type`.\n- Every response from a documented endpoint carries a `Request-Id` header; quote it when contacting support.\n- Rate-limited requests answer `429`; denials made at the API edge carry `RateLimit-*` and `Retry-After` headers.\n", "contact": { "name": "Synthesia developer docs", "url": "https://developers.synthesia.io/docs" } }, "paths": { "/api/interactive-avatars/sessions": { "post": { "tags": [ "interactive-avatars" ], "summary": "Start an interactive avatar session", "description": "Start an interactive avatar session.\n\n- Each running session counts toward your plan's concurrent-session limit until it ends.\n- Only sessions started through this API count toward the limit.\n- Over the limit, the request fails with `429` and code `concurrency_limit`; its `detail`\n states your plan's limit and how many sessions are running.\n\n| Plan | Concurrent sessions |\n| --- | --- |\n| Freemium | 1 |\n| All paid plans | 100 |\n\n**Required scope:** [`interactive_avatars:write`](https://developers.synthesia.io/docs/scopes) (in Studio: Interactive Avatars (write))", "operationId": "createInteractiveAvatarSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewSession" }, "examples": { "default": { "summary": "Start an interactive avatar session", "value": { "avatarIds": [ "av_6c9edb85a2f947e5" ], "livekitUrl": "wss://your-app.livekit.cloud", "livekitToken": "" } } } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/MalformedOrInvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "description": "Your plan does not include interactive avatars (feature_not_in_plan), or the session quota is exhausted (quota_exceeded).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "$ref": "#/components/responses/InsufficientlyScopedOrForbidden" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "The LiveKit room was closed, or the avatar's participant was removed from it, while the session was starting (conflict).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "description": "Rate limited, or the concurrent session limit is reached. When known, the concurrency detail includes your plan's numbers: \"Your plan allows 1 concurrent session and 1 is already running. End an active session or wait for one to end.\" Both 429 kinds carry a Retry-After header when a wait interval is known.", "headers": { "RateLimit-Limit": { "description": "Requests allowed in the window. Sent on the facade's own rate-limit denials.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the window. Sent on the facade's own rate-limit denials.", "schema": { "type": "integer" } }, "RateLimit-Reset-At": { "description": "Unix epoch seconds when the window resets, the value the v2 API sends as RateLimit-Reset. Retry-After carries the delta. Sent on the facade's own rate-limit denials.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying, when known.", "schema": { "type": "integer" } }, "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/UpstreamTimeout" } }, "security": [ { "ApiKeyAuth": [ "interactive_avatars:write" ] } ], "x-deadline-seconds": 75, "x-required-scope": "interactive_avatars:write" } } }, "components": { "schemas": { "NewSession": { "properties": { "avatarIds": { "items": { "type": "string", "description": "The avatar id, prefixed `av_…`." }, "type": "array", "minItems": 1, "title": "Avatar Ids", "description": "The interactive avatars to join the session — e.g. the id returned by POST /api/interactive-avatars/avatars once its status is completed.", "examples": [ [ "av_6c9edb85a2f947e5" ] ], "example": [ "av_6c9edb85a2f947e5" ] }, "livekitUrl": { "type": "string", "minLength": 1, "title": "Livekit Url", "description": "The WebSocket URL (wss://…) of your LiveKit room the avatar joins.", "examples": [ "wss://your-app.livekit.cloud" ], "example": "wss://your-app.livekit.cloud" }, "livekitToken": { "type": "string", "minLength": 1, "title": "Livekit Token", "description": "A LiveKit access token you mint for the avatar's participant in that room. If you retry a failed request, reuse the same livekitUrl and livekitToken.", "examples": [ "" ], "example": "" } }, "additionalProperties": false, "type": "object", "required": [ "avatarIds", "livekitUrl", "livekitToken" ], "title": "NewSession", "description": "A session runs in your own LiveKit room: the avatar joins it as a participant. Synthesia\ndoes not host the room, mint LiveKit tokens, or carry the media." }, "Problem": { "properties": { "type": { "type": "string", "title": "Type", "description": "A URL identifying the error class — documentation, not a contract: branch on `code`, never parse `type`." }, "title": { "type": "string", "title": "Title", "description": "A human-readable summary of the error class." }, "status": { "type": "integer", "title": "Status", "description": "The HTTP status code, repeated from the response." }, "code": { "type": "string", "title": "Code", "description": "The stable, machine-readable error code to branch on. New codes may appear; treat an unknown one by its `status`." }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail", "description": "Human-readable specifics; the wording may change without notice." }, "features": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Features", "description": "On `feature_not_in_plan` only: the plan features this request needs." }, "instance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instance", "description": "The request path that produced the error." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id", "description": "Identifies the request in Synthesia's logs (also the `Request-Id` header); quote it when contacting support." } }, "type": "object", "required": [ "type", "title", "status", "code" ], "title": "Problem", "description": "An error response in RFC 9457 Problem Details format." }, "Session": { "properties": { "id": { "type": "string", "title": "Id", "description": "The session id, prefixed `ses_…`.", "examples": [ "ses_6f2a91c04b8d4e37" ], "example": "ses_6f2a91c04b8d4e37" }, "status": { "type": "string", "title": "Status", "description": "Always \"active\": the session is live when this response returns." }, "createdAt": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the session became live.", "examples": [ "2026-09-10T09:30:00Z" ], "example": "2026-09-10T09:30:00Z" } }, "type": "object", "required": [ "id", "status", "createdAt" ], "title": "Session" } }, "securitySchemes": { "ApiKeyAuth": { "type": "http", "description": "Your Synthesia API key.\n\n- Send it as `Authorization: Bearer `; a bare key also works.\n- An endpoint that needs a scope names it in its description; [Scopes](https://developers.synthesia.io/docs/scopes) lists them all.\n- A `:write` scope also satisfies the same resource's `:read`.\n- Without the scope, the request fails with a 403 `insufficient_scope`.\n", "scheme": "bearer" } }, "responses": { "MalformedOrInvalidRequest": { "description": "Malformed or invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Unauthenticated": { "description": "Unauthenticated", "headers": { "WWW-Authenticate": { "description": "RFC 6750 Bearer challenge. `realm` alone when no key was sent; `error=\"invalid_request\"` for an Authorization scheme other than Bearer; `error=\"invalid_token\"` for a rejected or expired key (the body's `code` tells which).", "schema": { "type": "string" } }, "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InsufficientlyScopedOrForbidden": { "description": "Insufficiently scoped or forbidden", "headers": { "WWW-Authenticate": { "description": "Sent on `insufficient_scope`: RFC 6750 Bearer challenge with `error=\"insufficient_scope\"` and `scope` naming the scope the endpoint requires.", "schema": { "type": "string" } }, "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PayloadTooLarge": { "description": "Payload too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "UnsupportedMediaType": { "description": "Unsupported media type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "InternalError": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "ServiceUnavailable": { "description": "Service unavailable", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, when known.", "schema": { "type": "integer" } }, "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UpstreamTimeout": { "description": "Upstream timeout", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "headers": { "RequestId": { "description": "The id of this request's audit record. Quote it when reporting a problem.", "schema": { "type": "string" } } } }, "tags": [ { "name": "interactive-avatars", "description": "Real-time interactive avatars: create an interactive avatar from a Studio avatar and run live sessions in your own LiveKit room." } ], "servers": [ { "url": "https://developers.synthesia.io" } ] } ``` # Sibling pages * [Interactive Avatar: Concepts](https://docs.synthesia.io/reference/ia-concepts.md) * [Interactive Avatar: Integration Overview](https://docs.synthesia.io/reference/ia-overview.md) * [Interactive Avatar: LiveKit Plugin reference](https://docs.synthesia.io/reference/ia-livekit-plugin-reference.md) * [Interactive Avatar: Quickstarts](https://docs.synthesia.io/reference/interactive-avatar-quickstarts.md) * [Create an interactive avatar](https://docs.synthesia.io/reference/createinteractiveavatar.md) * [Interactive Avatars: Operational trust](https://docs.synthesia.io/reference/ia-operational-trust.md)