アバタービデオ
アバター、音声、スクリプト、シーン、背景を完全に制御してAIアバタービデオを作成します。HeyGenの/v2/video/generateAPIを使用して、シングルシーンまたはマルチシーンビデオを正確な設定で構築します。
認証
すべてのリクエストにX-Api-Keyヘッダーが必要です。HEYGEN_API_KEY環境変数を設定してください。
curl -X GET "https://api.heygen.com/v2/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY"
ツール選択
HeyGen MCPツール(mcp__heygen__*)が利用可能な場合は、それらを優先してください。認証とリクエストのフォーマットを自動的に処理します。
| タスク | MCPツール | フォールバック(直接API) |
|---|---|---|
| ビデオステータスの確認 / URL取得 | mcp__heygen__get_video | GET /v2/videos/{video_id} |
| アカウントのビデオ一覧 | mcp__heygen__list_videos | GET /v2/videos |
| ビデオの削除 | mcp__heygen__delete_video | DELETE /v2/videos/{video_id} |
ビデオ生成(POST /v2/video/generate)とアバター/音声一覧は、直接API呼び出しで行います。以下のリファレンスファイルを参照してください。
デフォルトワークフロー
- アバター一覧 —
GET /v2/avatars→ アバターを選択、プレビューし、avatar_idとdefault_voice_idを確認。詳細はavatars.mdを参照 - 音声一覧(必要な場合) —
GET /v2/voices→ アバターの性別/言語に一致する音声を選択。詳細はvoices.mdを参照 - スクリプト作成 — 各シーンを1つのコンセプトで構造化。詳細はscripts.mdを参照
- ビデオ生成 —
POST /v2/video/generateにアバター、音声、スクリプト、シーンごとの背景を指定。詳細はvideo-generation.mdを参照 - 完了までポーリング —
GET /v2/videos/{video_id}でステータスがcompletedになるまで確認。詳細はvideo-status.mdを参照
クイックリファレンス
| タスク | 参照先 |
|---|---|
| アバターの一覧とプレビュー | avatars.md |
| 音声の一覧と選択 | voices.md |
| スクリプトの作成と構造化 | scripts.md |
| ビデオ生成(シングル/マルチシーン) | video-generation.md |
| カスタム背景の追加 | backgrounds.md |
| キャプション/字幕の追加 | captions.md |
| テキストオーバーレイの追加 | text-overlays.md |
| 透明WebMビデオの作成 | video-generation.md(WebMセクション) |
| テンプレートの使用 | templates.md |
| 写真からのアバター作成 | photo-avatars.md |
| ビデオステータスの確認 / ダウンロード | video-status.md |
| アセットのアップロード(画像、音声) | assets.md |
| Remotionとの連携 | remotion-integration.md |
| Webhookの設定 | webhooks.md |
このスキルを使用するタイミングと「Create Video」スキルの違い
このスキルは精密な制御が必要な場合に使用します。アバターを選択し、正確なスクリプトを書き、各シーンを設定します。
ユーザーが単にビデオのアイデアを説明し、残り(スクリプト、アバター、ビジュアル)をAIに任せたい場合は、代わりにcreate-videoスキルを使用してください。
| ユーザーが言ったこと | Create Videoスキル | このスキル |
|---|---|---|
| 「Xについてのビデオを作って」 | ✓ | |
| 「製品デモを作成して」 | ✓ | |
| 「アバターYにZと正確に言わせたい」 | ✓ | |
| 「異なる背景のマルチシーンビデオ」 | ✓ | |
| 「合成用の透明WebM」 | ✓ | |
| 「スクリプトにこの特定の音声を使用する」 | ✓ | |
| 「正確な仕様でビデオをバッチ生成する」 | ✓ |
リファレンスファイル
コアビデオ作成
- references/avatars.md - アバター一覧、スタイル、avatar_idの選択
- references/voices.md - 音声一覧、ロケール、速度/ピッチ
- references/scripts.md - スクリプト作成、ポーズ、ペーシング
- references/video-generation.md - POST /v2/video/generateとマルチシーンビデオ
ビデオカスタマイズ
- references/backgrounds.md - 単色、画像、ビデオ背景
- references/text-overlays.md - フォントと位置指定によるテキスト追加
- references/captions.md - 自動生成キャプションと字幕
高度な機能
- references/templates.md - テンプレート一覧と変数置換
- references/photo-avatars.md - 写真からのアバター作成
- references/webhooks.md - Webhookエンドポイントとイベント
統合
- references/remotion-integration.md - RemotionコンポジションでのHeyGen使用
基礎
- references/video-status.md - ポーリングパターンとダウンロードURL
- references/assets.md - 画像、ビデオ、音声のアップロード
- references/dimensions.md - 解像度とアスペクト比
- references/quota.md - クレジットシステムと使用制限
ベストプラクティス
- 生成前にアバターをプレビュー —
preview_image_urlをダウンロードして、ユーザーがアバターを確認してから決定できるようにする - アバターのデフォルト音声を使用 — ほとんどのアバターには自然な結果を得るために事前にマッチングされた
default_voice_idがあります - フォールバック:手動で性別を合わせる — デフォルト音声がない場合、アバターと音声の性別が一致することを確認
- 開発時はテストモードを使用 —
test: trueを設定してクレジット消費を回避(出力には透かしが入ります) - 余裕のあるタイムアウトを設定 — ビデオ生成には5〜15分かかる場合が多く、それ以上かかることもあります
- 入力を検証 — 生成前にアバターIDと音声IDが存在することを確認