建立影片
從一段文字提示詞生成完整影片。描述您想要的內容,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) - 使用傳回的 video_id 呼叫
mcp__heygen__get_video以輪詢狀態並取得下載網址
不使用 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確保影片間的一致性 - 上傳參考檔案——協助影片代理人理解您的品牌/產品
- 疊代提示詞——根據結果進行改良;影片代理人非常適合快速疊代