動画を作成する
テキストプロンプトから完全な動画を生成します。必要な内容を説明するだけで、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__*)が利用可能な場合は、それらを優先して使用してください。認証とリクエストフォーマットを自動処理します。
| タスク | 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呼び出しを使用します。
デフォルトワークフロー
常にプロンプト最適化ガイドのガイドラインに従い、シーン、タイミング、ビジュアルスタイルを構造化したプロンプトを作成します。
MCPツールを使用する場合:
- プロンプト最適化ガイド → ビジュアルスタイルを使用して最適化されたプロンプトを作成
mcp__heygen__generate_video_agentをプロンプトと設定(duration_sec、orientation、avatar_id)で呼び出すmcp__heygen__get_videoを返されたvideo_idで呼び出し、ステータスをポーリングしてダウンロードURLを取得
MCPツールなし(直接API)の場合:
- プロンプト最適化ガイド → ビジュアルスタイルを使用して最適化されたプロンプトを作成
POST /v1/video_agent/generate— ビデオエージェントを参照GET /v2/videos/<id>— 動画ステータスを参照
クイックリファレンス
| タスク | MCPツール | 参照資料 |
|---|---|---|
| プロンプトから動画を生成 | mcp__heygen__generate_video_agent | プロンプト最適化ガイド → ビジュアルスタイル → ビデオエージェント |
| 動画のステータス確認/ダウンロードURL取得 | mcp__heygen__get_video | 動画ステータス |
| プロンプト用の参照ファイルをアップロード | — | アセット |
このスキルを使用するタイミング vs アバター動画スキル
このスキルはプロンプトベースの動画作成 — 必要な内容を説明するだけで、AIが残りを処理します。
ユーザーが特定のアバター、正確なスクリプト、シーンごとの音声/背景設定、複数シーン構成を細かく制御する必要がある場合は、代わりにアバター動画スキルを使用してください。
| ユーザーの発言 | このスキル | アバター動画スキル |
|---|---|---|
| 「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を使用して動画間の一貫性を確保 - 参照ファイルをアップロードする — エージェントがブランドや製品を理解するのに役立ちます
- プロンプトを反復改善する — 結果に基づいて改良。ビデオエージェントは素早い反復に最適です