建立影片
從一段文字提示產生完整的影片。描述您想要的内容,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 撰寫最佳化提示
- 呼叫
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以保持影片一致性 - 上傳參考檔案 — 幫助代理程式了解您的品牌/產品
- 迭代提示 — 根據結果進行調整;影片代理程式非常適合快速迭代