虛擬人物影片
使用 HeyGen /v2/video/generate API,以完整控制虛擬人物、聲音、腳本、場景與背景,建立 AI 虛擬人物影片。可建置單一或多場景影片,並精確設定組態。
驗證
所有請求都需要 X-Api-Key 標頭。請設定 HEYGEN_API_KEY 環境變數。
curl -X GET "https://api.heygen.com/v2/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY"
工具選擇
如果 HeyGen MCP 工具可用(mcp__heygen__*),請優先使用它們,而非直接呼叫 HTTP API——它們會自動處理驗證與請求格式。
| 任務 | MCP 工具 | 備用方案(直接 API) |
|---|---|---|
| 檢查影片狀態 / 取得網址 | 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} |
影片生成(POST /v2/video/generate)以及虛擬人物/聲音的列舉則透過直接 API 呼叫——請參閱下列參考檔案。
預設工作流程
- 列出虛擬人物 —
GET /v2/avatars→ 選擇一個虛擬人物,預覽它,記下avatar_id與default_voice_id。請參閱 avatars.md - 列出聲音(如有需要)—
GET /v2/voices→ 選擇與虛擬人物性別/語言相符的聲音。請參閱 voices.md - 編寫腳本 — 為每個場景建立一個概念的結構。請參閱 scripts.md
- 生成影片 —
POST /v2/video/generate,每個場景提供虛擬人物、聲音、腳本與背景。請參閱 video-generation.md - 輪詢直到完成 —
GET /v2/videos/{video_id}直到狀態變為completed。請參閱 video-status.md
快速參考
| 任務 | 閱讀 |
|---|---|
| 列出與預覽虛擬人物 | avatars.md |
| 列出與選擇聲音 | voices.md |
| 編寫與結構化腳本 | scripts.md |
| 生成影片(單一或多場景) | video-generation.md |
| 新增自訂背景 | backgrounds.md |
| 新增字幕 | captions.md |
| 新增文字覆蓋 | text-overlays.md |
| 建立透明 WebM 影片 | video-generation.md(WebM 章節) |
| 使用範本 | templates.md |
| 從照片建立虛擬人物 | photo-avatars.md |
| 檢查影片狀態 / 下載 | video-status.md |
| 上傳素材(圖片、音訊) | assets.md |
| 與 Remotion 一起使用 | remotion-integration.md |
| 設定網路鉤子 | webhooks.md |
何時使用此技能 vs. 建立影片
此技能是為了精確控制——你選擇虛擬人物,編寫確切腳本,設定每個場景。
如果使用者只想描述一個影片點子,讓 AI 處理其餘部分(腳本、虛擬人物、視覺效果),請改用 create-video 技能。
| 使用者說 | 建立影片技能 | 此技能 |
|---|---|---|
| "幫我做一個關於 X 的影片" | ✓ | |
| "建立一個產品展示" | ✓ | |
| "我想要虛擬人物 Y 準確說出 Z" | ✓ | |
| "多場景影片,每個場景不同背景" | ✓ | |
| "透明 WebM 以利合成" | ✓ | |
| "為我的腳本使用這個特定聲音" | ✓ | |
| "以精確規格批次生成影片" | ✓ |
參考檔案
核心影片建立
- references/avatars.md - 列出虛擬人物、樣式、avatar_id 選擇
- references/voices.md - 列出聲音、地區設定、速度/音高
- references/scripts.md - 編寫腳本、停頓、節奏
- references/video-generation.md - POST /v2/video/generate 與多場景影片
影片自訂
- references/backgrounds.md - 純色、圖片、影片背景
- references/text-overlays.md - 使用字型與定位新增文字
- references/captions.md - 自動生成的字幕
進階功能
- references/templates.md - 範本列出與變數替換
- references/photo-avatars.md - 從照片建立虛擬人物
- references/webhooks.md - 網路鉤子端點與事件
整合
- references/remotion-integration.md - 在 Remotion 組合中使用 HeyGen
基礎
- references/video-status.md - 輪詢模式與下載網址
- references/assets.md - 上傳圖片、影片、音訊
- references/dimensions.md - 解析度與長寬比
- references/quota.md - 點數系統與使用限制
最佳實踐
- 在生成前預覽虛擬人物 — 下載
preview_image_url,讓使用者在決定前能看到虛擬人物 - 使用虛擬人物的預設聲音 — 大多數虛擬人物都有預先配對的
default_voice_id,以獲得自然效果 - 備用方案:手動配對性別 — 如果沒有預設聲音,請確保虛擬人物與聲音的性別相符
- 使用測試模式進行開發 — 設定
test: true以避免消耗點數(輸出將帶有浮水印) - 設定充裕的超時時間 — 影片生成通常需要 5-15 分鐘,有時更長
- 驗證輸入 — 在生成前檢查虛擬人物與聲音 ID 是否存在