Skip to navigation
Synthesia API referenceinteractive-avatars

Create an interactive avatar

Create an interactive avatar from an existing Studio avatar.

  • Generation is asynchronous: the request answers 202 with the avatar’s current status.
  • Poll by repeating the same request (with regenerate omitted) until done is true — a repeat never starts a second generation.
  • Each poll re-runs the credit check, so a drained balance answers 402 even while an already-dispatched generation continues.
  • Once status is completed, include the returned id in the avatarIds list of POST /api/interactive-avatars/sessions.

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.
sourceIdstringRequired

The avatar id shown in Studio, with the av_ prefix.

regeneratebooleanOptionalDefaults to false
Force a fresh interactive avatar generation instead of returning the existing avatar.

Response headers

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

Response

Successful Response
idstring

The interactive avatar. Include it in the avatarIds list of POST /api/interactive-avatars/sessions.

statusenum

Poll by repeating the same request with regenerate omitted until done is true, then read this field: failed means the source cannot become an interactive avatar.

Allowed values:
donebooleanRead-only
True once generation has finished, whatever the outcome.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found 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