動画作成
テキストプロンプトから完全な動画を生成します。欲しい内容を説明するだけで、AIがスクリプト作成、アバター選択、ビジュアル、ナレーション、ペース調整、字幕を自動で処理します。
認証
すべてのリクエストには X-Api-Key ヘッダーが必要です。HEYGEN_API_KEY 環境変数を設定してください。
curl -X POST "https://api.heygen.com/v1/video_agent/generate" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "60秒の製品デモ動画を作成してください。"}'
ツール選択
HeyGen MCPツールが利用可能な場合(mcp__heygen__*)、直接HTTP API呼び出しよりもそれらを優先してください。これらは認証とリクエストフォーマットを自動的に処理します。
| タスク | MCPツール | フォールバック(直接API) |
|---|---|---|
| プロンプトから動画を生成 | mcp__heygen__generate_video_agent | POST /v1/video_agent/generate |
| 動画ステータス確認 / 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} |
HeyGen MCPツールが利用できない場合は、リファレンスファイルに記載されている直接HTTP API呼び出しを使用してください。
デフォルトワークフロー
プロンプトをシーン、タイミング、ビジュアルスタイルで構造化するために、常に prompt-optimizer.md ガイドラインを使用してください。
MCPツールを使用する場合:
- prompt-optimizer.md と visual-styles.md を使用して最適化されたプロンプトを作成します。
- プロンプトと設定(duration_sec、orientation、avatar_id)を指定して
mcp__heygen__generate_video_agentを呼び出します。 - 返された video_id を使用して
mcp__heygen__get_videoを呼び出し、ステータスをポーリングしてダウンロードURLを取得します。
MCPツールなし(直接API)の場合:
- prompt-optimizer.md と visual-styles.md を使用して最適化されたプロンプトを作成します。
POST /v1/video_agent/generate— video-agent.md を参照GET /v2/videos/<id>— video-status.md を参照
クイックリファレンス
| タスク | MCPツール | 参照先 |
|---|---|---|
| プロンプトから動画を生成 | mcp__heygen__generate_video_agent | prompt-optimizer.md → visual-styles.md → video-agent.md |
| 動画ステータス確認 / ダウンロードURL取得 | mcp__heygen__get_video | video-status.md |
| 参照ファイルをアップロード | — | assets.md |
このスキルを使用すべきタイミング vs アバター動画スキル
このスキルはプロンプトベースの動画作成向けです。欲しい内容を説明するだけで、AIが残りを処理します。
ユーザーが特定のアバター、正確なスクリプト、シーンごとの音声/背景設定、またはマルチシーン構成を正確に制御する必要がある場合は、代わりにavatar-videoスキルを使用してください。
| ユーザーの発言 | このスキル | アバター動画スキル |
|---|---|---|
| 「Xについての動画を作って」 | ✓ | |
| 「製品デモを作成して」 | ✓ | |
| 「アバターYにZを正確に言わせたい」 | ✓ | |
| 「異なる背景のマルチシーン動画」 | ✓ | |
| 「合成用の透明WebM」 | ✓ |
リファレンスファイル
コアワークフロー
- references/prompt-optimizer.md - 効果的なプロンプトの作成方法(コアワークフロー+ルール)
- references/visual-styles.md - 20の名前付きビジュアルスタイルと完全な仕様
- references/prompt-examples.md - 完全なプロダクションプロンプト例+すぐに使えるテンプレート
- references/video-agent.md - ビデオエージェントAPIエンドポイントの詳細
基礎
- references/video-status.md - ポーリングパターンとダウンロードURL
- references/webhooks.md - Webhookエンドポイントとイベント
- references/assets.md - 画像、動画、音声の参照ファイルのアップロード方法
- references/dimensions.md - 解像度とアスペクト比
- references/quota.md - クレジットシステムと使用制限
ベストプラクティス
- プロンプトを最適化 — 平凡な結果とプロフェッショナルな結果の差は、プロンプトの品質に完全に依存します。常にプロンプトオプティマイザーを使用してください。
- 長さを指定 — 予測可能な長さにするために
config.duration_secを使用します。 - 必要に応じてアバターを固定 — 動画間で一貫性を持たせるために
config.avatar_idを使用します。 - 参照ファイルをアップロード — エージェントがブランドや製品を理解するのに役立ちます。
- プロンプトを繰り返し改善 — 結果に基づいて改良します。ビデオエージェントは迅速な反復に最適です。