Avatar Video
Create AI avatar videos with full control over avatars, voices, scripts, and backgrounds using POST /v3/videos. Two creation modes via discriminated union on type:
- -
"type": "avatar" + avatar_id — use a HeyGen avatar from the library - INLINECODE4 +
image (AssetInput) — animate any photo via Avatar IV
Authentication
All requests require the X-Api-Key header. Set the HEYGEN_API_KEY environment variable.
CODEBLOCK0
Tool Selection
If HeyGen MCP tools are available (mcp__heygen__*), prefer them over direct HTTP API calls — they handle authentication and request formatting automatically.
| Task | MCP Tool | Fallback (Direct API) |
|---|
| Check video status / get URL | INLINECODE9 | INLINECODE10 |
| List account videos |
mcp__heygen__list_videos |
GET /v3/videos |
| Delete a video |
mcp__heygen__delete_video |
DELETE /v3/videos/{video_id} |
Video generation (POST /v3/videos) and avatar/voice listing are done via direct API calls — see reference files below.
Default Workflow
- 1. List avatar looks —
GET /v3/avatars/looks → pick a look, note its id (this is the avatar_id) and default_voice_id. See avatars.md - List voices (if needed) —
GET /v3/voices → pick a voice matching the avatar's gender/language. See voices.md - Write the script — Structure scenes with one concept each. See scripts.md
- Generate the video —
POST /v3/videos with avatar_id, voice_id, script, and optional background per scene. See video-generation.md - Poll for completion —
GET /v3/videos/{video_id} until status is completed. See video-status.md
Routing: This Skill vs Create Video
This skill = precise control (specific avatar, exact script, custom background).
create-video = prompt-based ("make me a video about X", AI handles the rest).
Reference Files
Read these as needed — they contain endpoint details, request/response schemas, and code examples (curl, TypeScript, Python).
Core workflow:
Customization:
Advanced:
Best Practices
- 1. Preview avatars before generating — Use
GET /v3/avatars/looks and download preview_image_url so the user can see the avatar before committing - Use avatar's default voice — Most avatars have a
default_voice_id pre-matched for natural results - Fallback: match gender manually — If no default voice, ensure avatar and voice genders match
- Use test mode for development — Set
test: true to avoid consuming credits (output will be watermarked) - Set generous timeouts — Video generation often takes 5-15 minutes, sometimes longer
- Validate inputs — Check avatar and voice IDs exist before generating
头像视频
通过 POST /v3/videos 创建AI头像视频，可完全控制头像、语音、脚本和背景。通过 type 的判别联合类型提供两种创建模式：
- - type: avatar + avatar_id — 使用HeyGen库中的头像
- type: image + image (AssetInput) — 通过Avatar IV为任意照片制作动画
身份验证
所有请求都需要 X-Api-Key 头信息。设置 HEYGENAPIKEY 环境变量。
bash
curl -X GET https://api.heygen.com/v3/avatars \
-H X-Api-Key: $HEYGENAPIKEY
工具选择
如果HeyGen MCP工具可用（mcpheygen*），优先使用它们而非直接HTTP API调用——它们会自动处理身份验证和请求格式化。
| 任务 | MCP工具 | 备用方案（直接API） |
|---|
| 检查视频状态/获取URL | mcpheygengetvideo | GET /v3/videos/{videoid} |
| 列出账户视频 |
mcp
heygenlist_videos | GET /v3/videos |
| 删除视频 | mcp
heygendelete
video | DELETE /v3/videos/{videoid} |
视频生成（POST /v3/videos）以及头像/语音列表通过直接API调用完成——详见下方参考文件。
默认工作流程
- 1. 列出头像外观 — GET /v3/avatars/looks → 选择一个外观，记录其 id（即 avatarid）和 defaultvoiceid。详见 avatars.md
- 列出语音（如需） — GET /v3/voices → 选择与头像性别/语言匹配的语音。详见 voices.md
- 编写脚本 — 每个场景结构包含一个概念。详见 scripts.md
- 生成视频 — POST /v3/videos，包含 avatarid、voiceid、script 以及每个场景可选的 background。详见 video-generation.md
- 轮询完成状态 — GET /v3/videos/{videoid} 直到状态变为 completed。详见 video-status.md
路由：本技能 vs 创建视频
本技能 = 精确控制（特定头像、精确脚本、自定义背景）。
create-video = 基于提示（给我做一个关于X的视频，AI处理其余部分）。
参考文件
根据需要阅读这些文件——它们包含端点详情、请求/响应模式以及代码示例（curl、TypeScript、Python）。
核心工作流程：
自定义：
高级：
最佳实践
- 1. 生成前预览头像 — 使用 GET /v3/avatars/looks 并下载 previewimageurl，让用户在确认前看到头像
- 使用头像的默认语音 — 大多数头像都有预先匹配的 defaultvoiceid，可获得自然效果
- 备用方案：手动匹配性别 — 如果没有默认语音，确保头像和语音性别匹配
- 开发时使用测试模式 — 设置 test: true 以避免消耗积分（输出将带有水印）
- 设置充足的超时时间 — 视频生成通常需要5-15分钟，有时更长
- 验证输入 — 生成前检查头像和语音ID是否存在
