アバタービデオ
アバター、音声、スクリプト、シーン、背景を完全に制御して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 |
| Webhookの設定 | 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 - 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が存在することを確認する