頭像影片
使用 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 皆存在