synthesia-interactive-avatar

Synthesia 交互式 Avatar 集成

Synthesia 交互式 Avatar 是 LiveKit Agents（Python）的插件组件。它会渲染逼真的口型同步 Avatar，并将其作为普通参与者发布到 LiveKit 房间。Agent 按照一贯的方式生成语音；该组件会将音频转发给 Synthesia 托管的 Avatar 工作进程，再由其将同步的音频和视频广播回房间。

此技能会评估用户已有的内容，选择一种集成方案并加以实现。

限制条件——开始前请先阅读

这些因素会影响所有建议。如果与用户相关，请一开始就告知：

• 需要获得访问权限。 API 密钥必须来自已开通交互式 Avatar 访问权限的 Synthesia 工作区；其他密钥会被拒绝（SynthesiaError，type 为 AUTH 或 FEATURE_NOT_IN_PLAN）。如果用户没有密钥，请停止操作，并引导他们前往 Synthesia 开发者控制台——没有密钥，构建的任何内容都无法运行。
• 仅支持 Python。 该插件面向 Python LiveKit Agents 框架，要求 Python 3.10+。不支持 Node.js Agent。
• 默认 Avatar： Kenji，"7572faa9-15da-400d-8227-ef1ab8932523"。AvatarConfig 接收 avatar_ids：包含一到五个图库 ID 的列表。第一个是当前使用的 Avatar；其余 Avatar 会预先计算好，以便 swap_avatar() 在会话期间切换到它们。除非用户指定其工作区中提供的其他 Avatar，否则只使用 Kenji。无法访问的 ID 会在 start() 时引发 SynthesiaError，其 type 为 UNKNOWN_AVATAR；如果传入的是字符串而不是列表，则会引发 ValueError。
• 没有沙盒。 与某些竞品不同，Synthesia 没有免费的沙盒 Avatar——每次会话都会计入工作区配额（超出上限时会引发 SynthesiaError，其 type 为 QUOTA_EXCEEDED，HTTP 状态码为 402）。
• 从 PyPI 安装： pip install "livekit-plugins-synthesia~=1.8"（或使用对应的 uv add 命令）。

第 1 步：了解用户已有的内容

先检查代码库和对话，再询问问题。代码库中已有答案的问题，不要再问。

自动扫描的线索

线索	查看位置	含义
livekit-agents / livekit.agents 导入语句	pyproject.toml、requirements.txt、导入语句	使用了 Python LiveKit Agent → 接入
AgentSession(llm=...realtime...)	Agent 入口文件	实时语音对语音模式
AgentSession(stt=..., llm=..., tts=..., vad=...)	Agent 入口文件	组件流水线模式
package.json 中的 @livekit/agents	Node 项目	Node Agent → 迁移或暂停（不支持）
livekit.plugins.tavus / bey / hedra / heygen	导入语句	使用了其他 LiveKit Avatar 插件 → 替换
对 api.heygen.com / api.liveavatar.com 的调用	代码、配置	HeyGen LiveAvatar 平台集成——请参阅下文的迁移说明
已导入 livekit.plugins.synthesia	导入语句	已有集成 → 排查问题，不要重建；转到 references/api-and-troubleshooting.md
SYNTHESIA_API_KEY	.env、密钥配置	已配置 Synthesia 密钥
LIVEKIT_URL / LIVEKIT_API_KEY / LIVEKIT_API_SECRET	.env、配置	已配置 LiveKit 凭据
OPENAI_API_KEY	.env	新建项目可默认使用 OpenAI Realtime
LiveKit 客户端 SDK / useVoiceAssistant	前端代码	已有 LiveKit 前端——Avatar 会自动显示在那里
Python 版本	pyproject.toml、python --version	必须为 3.10+
livekit-agents 版本	pyproject.toml、锁定文件、pip show livekit-agents	必须为 ≥ 1.8.2——插件对此有要求

要询问的问题（仅询问仍未知的信息）

用一份简洁的清单一次性询问，不要逐条提问：

To wire up the Synthesia Interactive Avatar, I need to know:

1. **Do you have a Synthesia API key from a workspace with Interactive Avatar access?** Access
   is gated — without this, every session is rejected, so it's the first thing to confirm.
2. **Do you already have a LiveKit Agent running?** (Python or Node? Realtime model, or your own
   STT + LLM + TTS pipeline?)
3. **If we're building from scratch:** do you have an OpenAI API key (for a Realtime voice
   model), or do you have preferred STT/LLM/TTS providers?

如果代码库或对话中已有答案，则跳过相应问题。

步骤 2：选择一种路径

始终选择可行的最简单路径。直接做出决定，不要提供选项菜单。

Existing livekit.plugins.synthesia code already present?
  → DEBUG — read references/api-and-troubleshooting.md, fix in place

Working Python LiveKit Agent (realtime OR pipeline)?
  → ATTACH — three-line pattern, implemented inline below

Python agent using another LiveKit avatar plugin (tavus / bey / hedra / heygen)?
  → SWAP — near drop-in replacement, see below

LiveKit Agent exists but it's Node.js?
  → PORT OR PAUSE — plugin is Python-only. If the agent is simple, offer to port the
    entrypoint to Python; otherwise the honest answer is to wait for broader support.

No agent at all?
  → GREENFIELD — scaffold a minimal Python agent + avatar.
    Default: OpenAI Realtime (fewest moving parts, one extra key).
    Use the component pipeline variant only if the user lacks Realtime access or
    explicitly wants specific STT/LLM/TTS providers.
    → read references/greenfield-quickstart.md and follow it end-to-end

然后用 2–3 句话告诉用户你推荐什么以及原因，并直接开始实施。例如：

你已经有一个可正常运行的管线 Agent（Deepgram STT + GPT-4o + ElevenLabs TTS），因此适合采用 接入：安装插件，在入口点添加三行代码，虚拟形象就会与现有 TTS 同步口型。无需更改管线或前端。

步骤 3：实施

路径：接入（现有 Python Agent）

实时 Agent 和管线 Agent 的接入方式完全相同——无论音频由什么生成，该组件都会拦截 session.output.audio。

1. 安装：uv add "livekit-plugins-synthesia~=1.8"（或使用 pip 对应命令）。如果 livekit-agents 的固定版本低于 1.8.2，请先提高版本；该插件需要此版本。
2. 将 SYNTHESIA_API_KEY 添加到 Agent 的环境中（密钥管理器或 .env——切勿硬编码，也不要放在前端代码中）。
3. 在入口点中，构建 AgentSession 后、调用 session.start(...) 之前：

from livekit.plugins import synthesia

avatar = synthesia.AvatarSession(
    synthesia.AvatarConfig(avatar_ids=["7572faa9-15da-400d-8227-ef1ab8932523"]),  # Kenji
)
await avatar.start(session, room=ctx.room)

4. 如果用户希望在会话中途切换虚拟形象，请提前传入所有 ID（最多五个——只能切换到预先计算好的 ID），并调用：

await avatar.swap_avatar("<another-id-from-avatar-ids>")  # switch mid-session
await avatar.swap_avatar("default")                       # back to the first id

集成就完成了。无需更改前端：虚拟形象会作为普通 LiveKit 参与者加入，因此任何 LiveKit 客户端都会自动渲染它。

路径：替换（从其他 LiveKit 虚拟形象插件迁移）

LiveKit 已统一虚拟形象插件模式，因此通常只需修改三行：

现有代码	替换为
from livekit.plugins import tavus（或 bey、hedra、heygen）	from livekit.plugins import synthesia
tavus.AvatarSession(replica_id=..., persona_id=...) 等	synthesia.AvatarSession(synthesia.AvatarConfig(avatar_ids=["7572faa9-15da-400d-8227-ef1ab8932523"]))
TAVUS_API_KEY / 服务提供商环境变量	SYNTHESIA_API_KEY

保留原有的 await avatar.start(session, room=ctx.room) 调用及其位置。从依赖项中移除旧插件的额外组件，并添加 synthesia 额外组件。

**专门从 HeyGen LiveAvatar 迁移：**如果他们使用的是 HeyGen 的 LITE 模式（通过 WebSocket 驱动自己的 STT + LLM + TTS 管线），那么他们已经有完整的管线——围绕这些相同的服务提供商构建 LiveKit AgentSession，然后采用 接入。如果他们使用的是 HeyGen 的 FULL 模式（由 HeyGen 托管整个管线），那么他们没有自己的管线——按 从头开始 处理。无论哪种情况，都要删除他们的 X-API-KEY / livekit_client_token 相关代码；Synthesia 组件会在 Agent 进程中自行生成房间令牌。

路径：从头开始

阅读 references/greenfield-quickstart.md 并按其说明操作。该文件包含完整的 .env 模板、两种 Agent 变体（实时和管线）、前端选项以及运行说明。

适用于所有路径的原则

• 先附加，再启动。 await avatar.start(session, room=ctx.room) 必须在 await session.start(...) 之前完成。顺序错误 → 虚拟形象不会出现，而且通常不会报错。
• 附加后，切勿重新赋值 session.output.audio。 该组件负责管理音频路由；覆盖它会在无提示的情况下破坏唇形同步。
• 让语音与虚拟形象匹配。 虚拟形象会根据模型生成的语音进行唇形同步——人设不匹配（例如，在男性形象上使用女性风格的语音）会显得不协调。请从提供商的语音列表中提议合适的语音（OpenAI Realtime、OpenAI TTS 或用户的 TTS 提供商），并与用户确认，不要直接采用默认语音。
• API 密钥必须保留在 Agent 进程中。 这是绑定工作区的密钥。如果发现 SYNTHESIA_API_KEY 即将进入前端代码，请立即停止并调整结构。
• 两种不同的“控制台”，切勿混为一谈。 终端运行模式（python agent.py console）是本地模拟房间：虚拟形象永远不会出现在那里，也不会报错。LiveKit Cloud Agent Console（仪表板 → 项目 → Agents → Console）则恰恰相反——这是一个真实的浏览器房间，会为虚拟形象 Agent 渲染视频，也是最快的测试地点。因此：使用 dev 运行，在 Agent Console 中测试。与用户交流时，请明确区分“终端 console 运行模式”和“LiveKit Cloud Agent Console”——如果只说“不要使用 console”，用户可能会误以为是在警告他们不要使用实际上应该使用的工具。
• 访问权限检查应尽早失败。 在编写大量代码之前，先验证 API 密钥是否有效：在 dev 模式下快速运行，即可立即触发 SynthesiaError，其 type 为 AUTH 或 FEATURE_NOT_IN_PLAN（没有 Interactive Avatar 访问权限）。
• 正确处理可重试错误。 根据 e.retryable 分支处理（if not e.retryable: raise）。可重试类型：TIMEOUT（抛出 join_timeout——冷启动可能发生）、CONNECTION、RATE_LIMITED 和 CONCURRENCY_LIMIT（遵守 e.retry_after）。其他所有情况都是配置问题，应提示用户，而不是循环重试。

完整的参数、方法、事件和异常表，以及症状→修复方案排查矩阵，见 references/api-and-troubleshooting.md。每当出现错误名称或行为不符合预期时，都请查阅该文档。

第 4 步：验证并收尾

1. 运行 python agent.py dev，然后连接。最快的方式：LiveKit Cloud Agent Console——仪表板 → 同一个项目 → Agents → Console → 按 agent_name 选择 Agent（样板代码中为 synthesia-avatar-agent）→ Start session。也可以使用用户自己的 LiveKit 前端。
2. 确认虚拟形象已加入，并在 join_timeout（默认 30 s）内发布视频。
3. 与 Agent 对话；确认虚拟形象的唇形同步与回复音频相匹配。
4. 确认没有密钥泄露到客户端。

查阅资料

• references/greenfield-quickstart.md — 完整脚手架：环境、安装、两种 Agent 变体、前端选项和运行说明。
• references/api-and-troubleshooting.md — AvatarSession / AvatarConfig 参数、方法、事件、异常及其可重试性，以及排查矩阵。
• Synthesia 开发者控制台 — API 密钥和用量。
• interactive-avatar-quickstarts/minimal — 端到端快速入门：Agent + 前端。可参考其中的前端和令牌端点；其 Agent 针对延迟进行了优化，超出了本技能模板的范围（虚拟形象相关代码行完全相同）。
• LiveKit Agents 文档 — 框架参考。