Interactive Avatar: LiveKit Plugin reference

Use this page when you're already building and need exact signatures, defaults, and failure behavior. For the mental model behind these objects, see Concepts; for runnable code, see the Quickstarts.

In Python, all symbols live in livekit.plugins.synthesia. In Node.js, import the plugin as import * as synthesia from '@livekit/agents-plugin-synthesia'. Examples that follow use Python naming unless a Node.js block is shown. In Node.js, parameters and methods use camelCase (avatarIds, swapAvatar()), and every duration is in milliseconds, not seconds.

Requirements

Python

• Python 3.10 or later. Tested on 3.10, 3.11 and 3.12.
• livekit-agents 1.8.2 or later, the plugin's only dependency, installed automatically.

Node.js

• @livekit/agents at the same version as the plugin, and @livekit/rtc-node 1.1.0 or later. Both are peer dependencies, so install them in your agent project if you haven't already.
• livekit-server-sdk 2.13.3 or later, installed automatically with the plugin.

Install the plugin:

pip install "livekit-plugins-synthesia~=1.8"

npm install @livekit/agents-plugin-synthesia

If you're following LiveKit's docs, livekit-agents[synthesia]~=1.8 installs the same package.

Environment variables

Read when the corresponding argument isn't passed explicitly.

All five are secrets and belong in your agent's environment or a secret manager. SYNTHESIA_API_KEY is workspace-bound and must never reach frontend code.

LIVEKIT_URL accepts https:// as well as wss://. The scheme is normalized before it reaches the avatar worker, so the https:// value LiveKit Cloud injects into deployed agents works unchanged.

Minimal usage

from livekit.plugins import synthesia

avatar = synthesia.AvatarSession(
    synthesia.AvatarConfig(avatar_ids=["<avatar-id>"]),
)
await avatar.start(session, room=ctx.room)   # before session.start()

import { voice } from '@livekit/agents';
import * as synthesia from '@livekit/agents-plugin-synthesia';

const session = new voice.AgentSession(/* ... */);

const avatar = new synthesia.AvatarSession(
  new synthesia.AvatarConfig({
    avatarIds: ['<avatar-id>'],
  }),
);
await avatar.start(session, ctx.room); // before session.start()

The plugin replaces session.output.audio, so the avatar lip-syncs whatever speech your agent produces. You can swap STT, LLM or TTS providers freely and these two lines never change.

synthesia.AvatarSession

AvatarSession(
    avatar_config,
    *,
    api_key=None,
    api_url=None,
    join_timeout=30.0,
    avatar_participant_identity=None,
    avatar_participant_name=None,
)

new synthesia.AvatarSession(
  avatarConfig,
  {
    apiKey,
    apiUrl,
    joinTimeout,
    avatarParticipantIdentity,
    avatarParticipantName,
  }, // options are optional
)

The table lists Python names and units. In Node.js, the second argument is an optional options object with the camelCase equivalents: apiKey, apiUrl, joinTimeout, avatarParticipantIdentity and avatarParticipantName. joinTimeout is in milliseconds and defaults to 30000.

Passing an empty or whitespace-only string for either participant field raises SynthesiaError. Omit them to take the defaults.

Properties

In Node.js the properties are avatarIdentity and provider, plus sessionId, which holds the Synthesia session ID once the session has started and is null before that. Quote it when contacting support.

synthesia.AvatarConfig

AvatarConfig(avatar_ids)

new synthesia.AvatarConfig({ avatarIds })

avatar_ids is validated when you construct the config, not when the session starts:

• A bare string instead of a list raises ValueError in Python and TypeError in Node.js.
• Fewer than one or more than five ids raises ValueError in Python and an Error in Node.js.

An id your workspace can't access raises SynthesiaError with type=ErrorType.UNKNOWN_AVATAR later, at start().

Pass every avatar you might swap to up front. Adding one afterwards requires a new session.

Methods

await avatar.start(agent_session, room, *, livekit_url=None, livekit_api_key=None, livekit_api_secret=None)

await avatar.start(agent_session, room, livekit_url=None, livekit_api_key=None, livekit_api_secret=None)

await avatar.start(agentSession, room, {
  livekitUrl,
  livekitApiKey,
  livekitApiSecret,
}); // options are optional

Mounts the avatar into room, launches the worker, and wires session.output.audio. Returns once the avatar has joined and published its video track.

Call this before AgentSession.start(). LiveKit credentials fall back to LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET.

The room must already be connected, because the plugin mints the avatar's token on behalf of your agent's identity and needs one to exist. Connect the room, then attach the avatar.

Calling start() on an already-started session returns immediately and does nothing. Calling it while another start() is still running raises SynthesiaError.

await avatar.swap_avatar(avatar_id, *, timeout=15.0)

In Node.js the signature is await avatar.swapAvatar(avatarId, { timeout }), where timeout is in milliseconds and defaults to 15000.

Switches the rendered avatar mid-session to another id from avatar_ids. Pass "default" to return to the first id. Returns the now-active avatar id once the swap has taken effect.

await avatar.swap_avatar("<another-id-from-avatar-ids>")
await avatar.swap_avatar("default")

await avatar.swapAvatar('<another-id-from-avatarIds>');
await avatar.swapAvatar('default');

Raises SynthesiaError if the session hasn't started or is shutting down, type=ErrorType.UNKNOWN_AVATAR if the target wasn't in avatar_ids, and type=ErrorType.CONNECTION if the swap request to the worker fails. A swap the worker rejects outright raises SynthesiaError with no type set.

await avatar.aclose()

Cooperative shutdown; restores normal audio routing. Called automatically when the room disconnects, or when the avatar drops unexpectedly.

Events

avatar.on("session_ended", lambda: ...)
avatar.on("error", lambda exc: ...)

session_ended means you or your user ended the session; error means the avatar went away on its own. Either one triggers shutdown automatically, so you don't need to call aclose() in the handler.

Exceptions

Every failure raises SynthesiaError, which subclasses LiveKit's livekit.agents.APIError, so you can catch Synthesia failures alongside every other plugin's. There is no exception hierarchy below it. To tell failures apart, read the type attribute.

ErrorType

Some failures carry no type at all, including a missing API key and a swap the worker rejects. Handle type is None rather than assuming every SynthesiaError is classified.

try:
    await avatar.start(session, room=ctx.room)
except synthesia.SynthesiaError as e:
    if e.type in (
        synthesia.ErrorType.QUOTA_EXCEEDED,
        synthesia.ErrorType.FEATURE_NOT_IN_PLAN,
    ):
        ...   # fall back to an audio-only session
    raise

try {
  await avatar.start(session, ctx.room);
} catch (e) {
  if (
    e instanceof synthesia.SynthesiaError &&
    (e.type === synthesia.ErrorType.QUOTA_EXCEEDED ||
      e.type === synthesia.ErrorType.FEATURE_NOT_IN_PLAN)
  ) {
    // fall back to an audio-only session
  }
  throw e;
}

Retry guidance

Branch on retryable, not on type; the plugin sets it per failure for exactly this decision. Honor retry_after when it's set. For a TIMEOUT failure, raise join_timeout before retrying, since cold starts are the usual cause.

Starting a session does not retry internally. A transient server error surfaces immediately as SynthesiaError with type=ErrorType.CONNECTION, so retrying is yours to do.

Never wrap auth, plan, quota, unknown-avatar, or validation failures in a retry loop.

For the HTTP-level error codes behind these error types, see Errors.

Troubleshooting

Choosing an avatar

Only synthetic and personal avatars work. Stock actor-based avatars (for example Ryan or Ada) can't be used as interactive avatars, whatever your plan.

For an eligible avatar your plan gives you access to:

1. Copy its ID from the Avatars page: open the ••• menu and select Copy ID.
2. Convert it with POST /api/interactive-avatars/avatars. Poll until status is completed, then pass the returned id in avatar_ids.

A repeat request for the same source returns the existing interactive avatar rather than starting a new conversion. Converting a stock avatar, or one outside your plan, returns an error rather than an interactive avatar.

Additional resources

• LiveKit's Synthesia integration guide: LiveKit's own setup walkthrough for this plugin.
• livekit-plugins-synthesia on PyPI
• @livekit/agents-plugin-synthesia on npm