synthesia-interactive-avatar

Synthesia インタラクティブアバター統合

Synthesia インタラクティブアバターは、LiveKit Agents（Python）用のプラグインコンポーネントです。フォトリアルなリップシンクアバターを描画し、通常の参加者として LiveKit ルームに公開します。エージェントはこれまでどおり音声を生成し、このコンポーネントがその音声を Synthesia のホスト型アバターワーカーに転送します。ワーカーは同期した音声と動画をルームにブロードキャストします。

このスキルでは、ユーザーがすでに用意しているものを確認し、統合方法を1つ選んで実装します。

制約 — 作業を始める前にお読みください

これらの制約は、すべての推奨事項に影響します。該当する場合は、最初にユーザーへ伝えてください。

• アクセス制限があります。 API キーは、インタラクティブアバターへのアクセス権がある Synthesia ワークスペースのものでなければなりません。それ以外のキーは拒否されます（SynthesiaError、type が AUTH または FEATURE_NOT_IN_PLAN）。キーがない場合は作業を中止し、Synthesia developer console を案内してください。キーなしでは、実装したものは何も動作しません。
• Python のみ対応しています。 このプラグインは Python LiveKit Agents フレームワークを対象としており、Python 3.10 以上が必要です。Node.js エージェントには対応していません。
• デフォルトのアバター： Kenji、"7572faa9-15da-400d-8227-ef1ab8932523"。AvatarConfig の avatar_ids は、ギャラリー ID を1〜5個含むリストを受け取ります。最初の ID がアクティブなアバターです。残りは事前に計算され、セッション中に swap_avatar() で切り替えられます。ユーザーがワークスペースで利用可能な別のアバターを指定しない限り、Kenji のみを使用してください。アクセスできない ID は start() で type が UNKNOWN_AVATAR の SynthesiaError を発生させます。リストの代わりに文字列を渡した場合は ValueError が発生します。
• サンドボックスはありません。 一部の競合サービスとは異なり、無料のサンドボックスアバターはありません。すべてのセッションがワークスペースのクォータに加算されます。上限に達すると、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...)	エージェントのエントリポイント	リアルタイムの音声から音声へのモード
AgentSession(stt=..., llm=..., tts=..., vad=...)	エージェントのエントリポイント	コンポーネントパイプラインモード
package.json の @livekit/agents	Node プロジェクト	Node エージェント → 移植するか、保留する（非対応）
livekit.plugins.tavus / bey / hedra / heygen	インポート	別の LiveKit アバタープラグインを使用 → 切り替え
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 フロントエンドが存在 — アバターは自動的に表示されます
Python のバージョン	pyproject.toml、python --version	3.10 以上が必要
livekit-agents のバージョン	pyproject.toml、ロックファイル、pip show livekit-agents	1.8.2 以上が必要 — プラグインが要求します

質問する内容（まだ分からないことのみ）

簡潔なチェックリストとしてまとめて質問し、1つずつ質問しないでください。

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：いずれか 1 つの経路を選ぶ

常に、機能する最もシンプルな方法を選びます。こちらで判断し、選択肢の一覧は提示しないでください。

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 文でユーザーに伝え、そのまま実装に進みます。例：

すでに動作するパイプラインエージェント（Deepgram STT + GPT-4o + ElevenLabs TTS）をお使いなので、これは Attach です。プラグインをインストールして、エントリーポイントに 3 行追加すれば、アバターが既存の TTS に合わせてリップシンクします。パイプラインやフロントエンドを変更する必要はありません。

ステップ 3：実装する

経路：ATTACH（既存の Python エージェント）

リアルタイムエージェントとパイプラインエージェントのどちらでも同じように動作します。このコンポーネントは、音声の生成元にかかわらず session.output.audio をインターセプトします。

1. インストールします：uv add "livekit-plugins-synthesia~=1.8"（または pip 相当のコマンド）。livekit-agents のバージョンが 1.8.2 未満の場合は、先に引き上げてください。このプラグインには 1.8.2 以降が必要です。
2. エージェントの環境に SYNTHESIA_API_KEY を追加します（シークレットマネージャーまたは .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 を事前に渡し（最大 5 つ。切り替えられるのは事前計算済みの 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 クライアントでも自動的に表示されます。

経路：SWAP（別の LiveKit アバタープラグインからの移行）

LiveKit ではアバタープラグインのパターンが標準化されているため、通常は 3 行の差分で済みます。

現在のコード	次のコードに置き換え
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 モード（独自の STT + LLM + TTS パイプラインで WebSocket を駆動する方式）を使用していた場合、すでにパイプラインが完成しています。同じプロバイダーを使って LiveKit の AgentSession を構築し、Attach してください。HeyGen の FULL モード（パイプライン全体を HeyGen がホストする方式）を使用していた場合は、独自のパイプラインがありません。Greenfield として扱ってください。どちらの場合も、X-API-KEY / livekit_client_token を扱うコードは削除してください。Synthesia コンポーネントが、エージェントのプロセス内でルームトークンを生成します。

経路：GREENFIELD

references/greenfield-quickstart.md を読み、手順に従ってください。.env の完全なテンプレート、2 種類のエージェント（リアルタイムとパイプライン）、フロントエンドの選択肢、実行手順が記載されています。

すべてのパスに適用される原則

• 開始前にアタッチします。 await avatar.start(session, room=ctx.room) が完了してから、await session.start(...) を実行する必要があります。順序を誤ると、アバターが表示されません。エラーが出ないこともよくあります。
• アタッチ後に session.output.audio を再割り当てしないでください。 このルーティングはコンポーネントが管理します。上書きすると、リップシンクがひそかに機能しなくなります。
• アバターに合った音声を選びます。 アバターはモデルが生成する音声に合わせてリップシンクします。ペルソナが合わない場合（例：男性に見えるアバターに女性のように聞こえる音声）は、動作不良のように見えます。プロバイダーのリスト（OpenAI Realtime、OpenAI TTS、またはユーザーの TTS プロバイダー）から適切な音声を提案し、デフォルトのまま提供するのではなく、ユーザーに確認してください。
• API キーはエージェントのプロセス内に保持します。 これはワークスペースに紐づくシークレットです。SYNTHESIA_API_KEY がフロントエンドのコードに渡されそうになっていたら、作業を止めて構成を見直してください。
• 「コンソール」は2種類あります。混同しないでください。 ターミナルの実行モード（python agent.py console）はローカルのモックルームです。アバターは表示されず、エラーも発生しません。一方、LiveKit Cloud Agent Console（ダッシュボード → プロジェクト → Agents → Console）は実際のブラウザルームで、アバターエージェントの動画が表示され、最も手早くテストできます。つまり、dev で実行し、Agent Console でテストします。ユーザーに説明するときは「ターミナルの console 実行モード」と「LiveKit Cloud Agent Console」を明確に区別してください。単に「コンソールは使わないでください」と言うと、使うべきツールについての警告だと誤解されます。
• アクセスの問題は早期に検出します。 大量のコードを書く前に API キーが有効か確認してください。dev モードですぐに実行すれば、type が AUTH または FEATURE_NOT_IN_PLAN（Interactive Avatar のアクセス権なし）の SynthesiaError がただちに発生します。
• 再試行の可否を尊重します。 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（ボイラープレートでは synthesia-avatar-agent）でエージェントを選択 → Start session。または、ユーザー自身の LiveKit フロントエンドを使います。
2. join_timeout（デフォルトは 30 s）以内にアバターが参加し、動画を配信することを確認します。
3. エージェントに話しかけ、アバターのリップシンクが応答音声と一致することを確認します。
4. クライアント側にシークレットが含まれていないことを確認します。

参照する資料

• references/greenfield-quickstart.md — 環境設定、インストール、2種類のエージェント、フロントエンドの選択肢、実行手順を含む完全なスキャフォールドです。
• references/api-and-troubleshooting.md — AvatarSession / AvatarConfig のパラメーター、メソッド、イベント、再試行可否を含む例外、およびトラブルシューティングマトリックスです。
• Synthesia developer console — API キーと使用方法です。
• interactive-avatar-quickstarts/minimal — エージェントとフロントエンドを含む、エンドツーエンドのクイックスタートです。フロントエンドとトークンエンドポイントを参考にしてください。エージェントはこのスキルのテンプレートよりも低レイテンシー向けに調整されています（アバターの部分は同一です）。
• LiveKit Agents docs — フレームワークのリファレンスです。