建立影片
從文字提示產生完整影片。描述您的需求,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 |
| 檢查影片狀態 / 取得網址 | 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 撰寫最佳化的提示
- 呼叫
mcp__heygen__generate_video_agent,並提供提示與設定(duration_sec、orientation、avatar_id) - 呼叫
mcp__heygen__get_video,並使用傳回的 video_id 來輪詢狀態並取得下載網址
不使用 MCP 工具(直接 API):
- 使用 prompt-optimizer.md → visual-styles.md 撰寫最佳化的提示
POST /v1/video_agent/generate——請參閱 video-agent.mdGET /v2/videos/<id>——請參閱 video-status.md
快速參考
| 任務 | MCP 工具 | 閱讀文件 |
|---|---|---|
| 從提示產生影片 | mcp__heygen__generate_video_agent | prompt-optimizer.md → visual-styles.md → video-agent.md |
| 檢查影片狀態 / 取得下載網址 | 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 —— 輪詢模式與下載網址
- references/webhooks.md —— Webhook 端點與事件
- references/assets.md —— 上傳圖片、影片、音訊作為參考
- references/dimensions.md —— 解析度與長寬比
- references/quota.md —— 點數系統與使用限制
最佳實務
- 最佳化您的提示 —— 平庸與專業結果之間的差異完全取決於提示品質。請務必使用提示最佳化工具
- 指定影片長度 —— 使用
config.duration_sec來控制可預測的長度 - 必要的話鎖定角色 —— 使用
config.avatar_id來確保跨影片的一致性 - 上傳參考檔案 —— 協助代理理解您的品牌/產品
- 反覆調整提示 —— 根據結果進行改善;影片代理非常適合快速迭代