create-video

動画の作成

テキストプロンプトから完成度の高い動画を生成します。作成したい内容を説明すると、AI がスクリプトの作成、アバターの選択、ビジュアル、ナレーション、ペース配分、字幕を自動で処理します。

認証

すべてのリクエストに X-Api-Key ヘッダーが必要です。HEYGEN_API_KEY 環境変数を設定してください。

curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a 60-second product demo video."}'

ツールの選択

HeyGen MCP ツール（mcp__heygen__*）が利用できる場合は、認証とリクエストの形式設定を自動で処理するため、直接 HTTP API を呼び出すよりも優先して使用してください。

タスク	MCP ツール	代替手段（直接 API）
プロンプトから動画を生成する	mcp__heygen__generate_video_agent	POST /v3/video-agents
動画のステータスを確認する／URL を取得する	mcp__heygen__get_video	GET /v3/videos/{video_id}
アカウントの動画一覧を取得する	mcp__heygen__list_videos	GET /v3/videos
動画を削除する	mcp__heygen__delete_video	DELETE /v3/videos/{video_id}

HeyGen MCP ツールが利用できない場合は、リファレンスファイルに記載されているとおり、直接 HTTP API を呼び出してください。

デフォルトのワークフロー

常に prompt-optimizer.md のガイドラインに従い、シーン、タイミング、ビジュアルスタイルを指定してプロンプトを構成してください。

MCP ツールを使用する場合：

1. prompt-optimizer.md → visual-styles.md を使用して、最適化されたプロンプトを作成します
2. プロンプトと設定（duration_sec、orientation、avatar_id）を指定して mcp__heygen__generate_video_agent を呼び出します
3. 返された video_id を指定して mcp__heygen__get_video を呼び出し、ステータスを確認してダウンロード URL を取得します

MCP ツールを使用しない場合（直接 API）：

1. prompt-optimizer.md → visual-styles.md を使用して、最適化されたプロンプトを作成します
2. POST /v3/video-agents — video-agent.md を参照してください
3. GET /v3/videos/<id> — video-status.md を参照してください

リファレンスファイル

必要に応じて参照してください。エンドポイントの詳細、リクエスト／レスポンスのスキーマ、コード例（curl、TypeScript、Python）が記載されています。

主要なワークフロー：

• references/prompt-optimizer.md — 効果的なプロンプトの作成（シーン、タイミング、ビジュアルスタイル）
• references/visual-styles.md — 詳細な仕様を含む20種類の名前付きビジュアルスタイル
• references/prompt-examples.md — 本番向けプロンプトの例とテンプレート
• references/video-agent.md — POST /v3/video-agents のリクエストフィールド、レスポンス形式、ファイル入力

基礎情報：

• references/video-status.md — GET /v3/videos/{id} によるステータス確認とダウンロード
• references/webhooks.md — Webhook エンドポイントとイベント
• references/assets.md — 参照用の画像、動画、音声のアップロード
• references/dimensions.md — 解像度とアスペクト比
• references/quota.md — クレジットシステムと利用上限

ベストプラクティス

1. プロンプトを最適化する — 品質はプロンプトの構成に完全に左右されます。常にプロンプトオプティマイザーを使用してください
2. 必要に応じてアバターを固定する — 動画間で一貫性を保つには avatar_id を指定します
3. 音声を指定する — 特定のナレーターの声を使用するには voice_id を指定します
4. 参照ファイルをアップロードする — エージェントがブランドや製品を理解するのに役立ちます
5. プロンプトを反復して改善する — 結果に基づいて調整します。Video Agent は迅速な反復に最適です