用途
Avatar Video 用于通过 HeyGen 的 v3 API（POST /v3/videos）创建 AI 数字人视频，并对数字人、声音、脚本和背景进行精确控制。它适合需要指定具体数字人形象、使用确切脚本内容以及自定义背景的视频制作场景。
主要能力
该技能通过 type 字段的判别联合提供两种创建模式：
- "type": "avatar" + avatar_id —— 使用 HeyGen 素材库中的数字人。
- "type": "image" + image（AssetInput）—— 通过 Avatar IV 让任意照片动起来。
此外，技能涵盖视频状态查询、视频列表、视频删除等操作，并提供脚本编写、背景、字幕、文字叠加、照片数字人、模板、Remotion 集成、Webhook、素材上传、分辨率与配额等参考文档。
使用方式
认证
所有请求都需要 X-Api-Key 请求头，并设置 HEYGEN_API_KEY 环境变量。示例：
curl -X GET "https://api.heygen.com/v3/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY"
工具选择
如果环境中提供 HeyGen MCP 工具（mcp__heygen__*），应优先使用它们而非直接 HTTP API 调用，因为它们会自动处理认证和请求格式。
| 任务 | MCP 工具 | 回退方案（直接 API） |
|---|---|---|
| 检查视频状态 / 获取 URL | mcp__heygen__get_video | GET /v3/videos/{video_id} |
| 列出账户视频 | mcp__heygen__list_videos | GET /v3/videos |
| 删除视频 | mcp__heygen__delete_video | DELETE /v3/videos/{video_id} |
视频生成（POST /v3/videos）以及数字人/声音列表通过直接 API 调用完成。
默认工作流
- 列出数字人形象 —— GET /v3/avatars/looks → 选择一个形象，记录其 id（即 avatar_id）和 default_voice_id。参见 avatars.md。
- 列出声音（如需要）—— GET /v3/voices → 选择与数字人性别/语言匹配的声音。参见 voices.md。
- 编写脚本 —— 按场景组织，每个场景一个概念。参见 scripts.md。
- 生成视频 —— POST /v3/videos，按场景传入 avatar_id、voice_id、script 以及可选背景。参见 video-generation.md。
- 轮询直至完成 —— GET /v3/videos/{video_id}，直到 status 为 completed。参见 video-status.md。
路由：本技能与 Create Video 的区别
- 本技能 = 精确控制（指定数字人、确切脚本、自定义背景）。
- create-video = 基于提示词（“帮我做一个关于 X 的视频”，由 AI 处理其余部分）。
参考文件
按需阅读以下文件，其中包含端点细节、请求/响应模式以及代码示例（curl、TypeScript、Python）。
核心工作流：
- references/video-generation.md —— POST /v3/videos 请求字段、数字人输入模式、声音设置、背景
- references/avatars.md —— GET /v3/avatars（分组）和 GET /v3/avatars/looks（形象 → avatar_id）
- references/voices.md —— GET /v3/voices，按语言、性别、引擎过滤
- references/video-status.md —— GET /v3/videos/{id} 轮询模式与下载
自定义：
- references/scripts.md —— 脚本编写、SSML break 标签、节奏
- references/backgrounds.md —— 纯色和图片背景
- references/captions.md —— 自动生成的字幕/副标题
- references/text-overlays.md —— 带字体和定位的文字叠加
高级：
- references/photo-avatars.md —— 通过 type: "image"（Avatar IV）让照片动起来，AI 生成数字人
- references/templates.md —— 模板列表与变量替换
- references/remotion-integration.md —— 在 Remotion 合成中使用 HeyGen 数字人
- references/webhooks.md —— Webhook 端点与事件
- references/assets.md —— 上传图片、视频、音频
- references/dimensions.md —— 分辨率与宽高比
- references/quota.md —— 积分系统与使用限制
适用场景
- 需要指定具体数字人形象并精确控制脚本内容的视频制作。
- 需要为不同场景设置自定义背景的视频。
- 需要将照片通过 Avatar IV 动画化为视频。
- 需要自动生成字幕、文字叠加或使用模板批量生成视频。
- 需要将 HeyGen 数字人集成到 Remotion 合成或通过 Webhook 接收事件。
限制
- 所有请求必须提供 X-Api-Key 请求头并设置 HEYGEN_API_KEY 环境变量。
- 视频生成通常需要 5-15 分钟，有时更长，需设置较宽松的超时。
- 开发时可设置 test: true 以避免消耗积分，但输出会带有水印。
- 生成前应验证 avatar 和 voice ID 是否存在。
- 若数字人没有默认声音，需手动确保数字人与声音的性别匹配。
- 关于收费、价格、平台支持等具体信息，资料中暂未提供。