用途
Avatar Video 用于创建 AI 数字人视频，可对数字人形象、声音、脚本、场景和背景进行完整控制。它基于 HeyGen 的 /v2/video/generate API，支持构建单场景或多场景视频，并按精确配置生成。
主要能力
- 列出并预览数字人，选择 avatar_id 和 default_voice_id
- 列出并选择声音，匹配数字人的性别与语言
- 编写和结构化脚本，按场景组织内容
- 生成单场景或多场景视频，每个场景可配置数字人、声音、脚本和背景
- 添加自定义背景（纯色、图片、视频）
- 添加字幕/说明文字
- 添加文字叠加层，支持字体与定位
- 创建透明 WebM 视频
- 使用模板并进行变量替换
- 从照片创建数字人
- 上传素材（图片、音频、视频）
- 与 Remotion 集成
- 设置 Webhook
- 检查视频状态并获取下载 URL
使用方式
认证
所有请求需要 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 Create Video
本技能用于精确控制——你选择数字人、编写确切脚本、配置每个场景。
如果用户只想描述视频创意并让 AI 处理其余部分（脚本、数字人、视觉），则使用 create-video 技能。
| 用户说 | 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 - 积分系统和使用限制
适用场景
- 需要指定数字人并让其说出精确脚本内容
- 制作多场景视频，每个场景使用不同背景
- 生成用于合成的透明 WebM 视频
- 为脚本指定特定声音
- 按精确规格批量生成视频
限制
- 需要 HeyGen API 密钥（HEYGEN_API_KEY）
- 视频生成通常需要 5-15 分钟，有时更长，需设置较宽松的超时
- 开发时可使用测试模式（test: true）避免消耗积分，但输出会带水印
- 生成前应验证数字人和声音 ID 是否存在
- 关于积分系统和使用限制的详细信息参见 references/quota.md
- 其他未在资料中说明的功能、收费、价格、平台或效果暂未提供