虛擬人物影片
使用 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) |
|---|---|---|
| 檢查影片狀態 / 取得 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} |
影片生成(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 |
| 設定 Webhook | 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 - Webhook 端點與事件
整合
- references/remotion-integration.md - 在 Remotion 合成中使用 HeyGen
基礎
- references/video-status.md - 輪詢模式與下載 URL
- references/assets.md - 上傳圖片、影片、音訊
- references/dimensions.md - 解析度與長寬比
- references/quota.md - 點數系統與使用限制
最佳實踐
- 在生成前預覽虛擬人物 — 下載
preview_image_url,讓使用者在確認前能看到虛擬人物 - 使用虛擬人物的預設語音 — 大多數虛擬人物都有預先匹配的
default_voice_id,以獲得自然效果 - 備用方案:手動匹配性別 — 如果沒有預設語音,請確保虛擬人物與語音的性別相符
- 開發時使用測試模式 — 設定
test: true以避免消耗點數(輸出將帶有浮水印) - 設定充裕的逾時時間 — 影片生成通常需要 5–15 分鐘,有時更長
- 驗證輸入 — 在生成前確認虛擬人物和語音 ID 是否存在