--- updatedAt: 2026-09-14T17:11:04.000Z agentTools: projectIndex: https://docs.synthesia.io/llms.txt --- # 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`](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/avatars": { "post": { "tags": [ "interactive-avatars" ], "summary": "Create an interactive avatar", "description": "Create an interactive avatar from an existing Studio avatar.\n\n- Generation is asynchronous: the request answers `202` with the avatar's current status.\n- Poll by repeating the same request (with `regenerate` omitted) until `done` is true — a\n repeat never starts a second generation.\n- Each poll re-runs the credit check, so a drained balance answers `402` even while an\n already-dispatched generation continues.\n- Once `status` is `completed`, include the returned `id` in the `avatarIds` list of\n `POST /api/interactive-avatars/sessions`.\n\n**Required scope:** [`interactive_avatars:write`](https://developers.synthesia.io/docs/scopes) (in Studio: Interactive Avatars (write))", "operationId": "createInteractiveAvatar", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewInteractiveAvatar" }, "examples": { "default": { "summary": "Create an interactive avatar", "value": { "sourceId": "av_6c9edb85a2f947e5", "regenerate": false } } } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractiveAvatar" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/MalformedOrInvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "description": "The workspace has no interactive avatar credits (no_credit). Top up or upgrade to create interactive avatars. Or you have run out of your monthly credit limit (user_credit_limit_reached): ask a workspace admin to raise it, or wait for it to reset.", "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" } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimited" }, "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": { "InteractiveAvatar": { "properties": { "id": { "type": "string", "title": "Id", "description": "The interactive avatar. Include it in the avatarIds list of POST /api/interactive-avatars/sessions.", "examples": [ "av_6c9edb85a2f947e5" ], "example": "av_6c9edb85a2f947e5" }, "status": { "$ref": "#/components/schemas/JobStatus", "title": "Status", "description": "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." }, "done": { "type": "boolean", "title": "Done", "description": "True once generation has finished, whatever the outcome.", "readOnly": true } }, "type": "object", "required": [ "id", "status", "done" ], "title": "InteractiveAvatar" }, "JobStatus": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "canceled" ], "title": "JobStatus" }, "NewInteractiveAvatar": { "properties": { "sourceId": { "type": "string", "title": "Source Id", "description": "The avatar id shown in Studio, with the av_ prefix.", "examples": [ "av_6c9edb85a2f947e5" ], "example": "av_6c9edb85a2f947e5" }, "regenerate": { "type": "boolean", "title": "Regenerate", "description": "Force a fresh interactive avatar generation instead of returning the existing avatar.", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "sourceId" ], "title": "NewInteractiveAvatar", "description": "The source to generate an interactive avatar from.\n\nRepeating a request returns the current status of the avatar generated from that source and never\nstarts a second generation - unless `regenerate` is true, which starts a fresh one on every call." }, "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." } }, "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" } } }, "RateLimited": { "description": "Rate limited", "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" } } } }, "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) * [Start an interactive avatar session](https://docs.synthesia.io/reference/createinteractiveavatarsession.md) * [Interactive Avatars: Operational trust](https://docs.synthesia.io/reference/ia-operational-trust.md)