虛擬人物影片
使用 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 |
| 設定 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 - 輪詢模式與下載網址
- references/assets.md - 上傳圖片、影片、音訊
- references/dimensions.md - 解析度與長寬比
- references/quota.md - 點數系統與使用限制
最佳實務
- 生成前先預覽虛擬人物 — 下載
preview_image_url,讓使用者在確定前先看到虛擬人物 - 使用虛擬人物的預設聲音 — 大多數虛擬人物都有預先配對好的
default_voice_id,能獲得自然的結果 - 備用方案:手動配對性別 — 如果沒有預設聲音,請確保虛擬人物與聲音的性別相符
- 開發時使用測試模式 — 設定
test: true以避免消耗點數(輸出會包含浮水印) - 設定寬裕的超時時間 — 影片生成通常需要 5-15 分鐘,有時更長
- 驗證輸入 — 在生成前檢查虛擬人物與聲音 ID 是否存在