アバタービデオ
アバター、音声、スクリプト、シーン、背景を完全に制御してAIアバタービデオを作成します。HeyGenの/v2/video/generate APIを使用して、単一または複数シーンのビデオを正確な設定で構築します。
認証
すべてのリクエストには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 |
| ウェブフックの設定 | webhooks.md |
このスキルを使用すべきタイミング vs 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 - ウェブフックエンドポイントとイベント
連携
- 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が存在することを確認します