Interactive Avatar: LiveKit Plugin reference

Complete reference for livekit-plugins-synthesia — every parameter, method, event, and exception. For the mental model behind these objects, see Concepts; for runnable code, see the Quickstarts.

All symbols live in livekit.plugins.synthesia.

Requirements

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

Install with pip:

pip install livekit-plugins-synthesia

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 normalised 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()

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,
)

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

Properties

synthesia.AvatarConfig

AvatarConfig(avatar_ids)

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

• A bare string instead of a list raises SynthesiaError.
• Fewer than one or more than five ids raises SynthesiaError.

An id your workspace can't access raises UnknownAvatarError 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)

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 — the plugin mints the avatar's token on behalf of your agent's identity, so it needs one. 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)

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")

Raises SynthesiaError if the session hasn't started or is shutting down, UnknownAvatarError if the target wasn't in avatar_ids, and SynthesiaConnectionError if the worker can't be reached.

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: ...)

The distinction is about who ended the session, not how bad it was: session_ended means you or your user ended it, error means the avatar went away on its own. Either one triggers shutdown automatically — you don't need to call aclose() in the handler.

Exceptions

Every exception subclasses SynthesiaError, which subclasses LiveKit's own livekit.agents.APIError. So you can catch Synthesia failures alongside every other plugin's, and every exception carries:

Retry guidance

Retry only the four retryable classes. Honour retry_after on RateLimitedError. For SynthesiaTimeoutError, raise join_timeout before retrying — cold starts are the usual cause.

Starting a session does not retry internally. A transient server error surfaces immediately as SynthesiaConnectionError, so retrying is yours to do.

Never wrap auth, plan, quota, unknown-avatar, token or validation errors in a retry loop. They won't resolve on their own; surface them with the fix.

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

Troubleshooting

Choosing an avatar

Synthetic and personal avatars only. Stock actor-based avatars (for example Ryan or Ada) can't be used as interactive avatars — this is a category restriction, not a plan or access issue.

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.