Skip to navigation
Synthesia API referenceinteractive-avatars

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.
PlanConcurrent sessions
Freemium1
All paid plans100

Required scope: interactive_avatars:write (in Studio: Interactive Avatars (write))

Authentication

AuthorizationBearer

Your Synthesia API key.

  • Send it as Authorization: Bearer <key>; a bare key also works.
  • An endpoint that needs a scope names it in its description; Scopes lists them all.
  • A :write scope also satisfies the same resource’s :read.
  • Without the scope, the request fails with a 403 insufficient_scope.

Request

This endpoint expects an object.
avatarIdslist of stringsRequired

The interactive avatars to join the session — e.g. the id returned by POST /api/interactive-avatars/avatars once its status is completed.

livekitUrlstringRequired>=1 character

The WebSocket URL (wss://…) of your LiveKit room the avatar joins.

livekitTokenstringRequired>=1 character
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.

Response headers

Request-IdstringOptional
The id of this request's audit record. Quote it when reporting a problem.

Response

Successful Response
idstring

The session id, prefixed ses_….

statusstring

Always “active”: the session is live when this response returns.

createdAtdatetime
When the session became live.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
415
Unsupported Media Type Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error
504
Gateway Timeout Error