動画作成
テキストプロンプトから完全な動画を生成します。内容を説明するだけで、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 - Video Agent 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を使用して動画間で一貫性を保つ - 参照ファイルをアップロードする — エージェントがブランドや製品を理解するのに役立ちます
- プロンプトを反復する — 結果に基づいて改良してください。Video Agentは素早い反復に最適です