用途
avatar-video 用于通过 HeyGen 的 /v2/video/generate API 创建 AI 数字人视频，并对数字人、声音、脚本、场景和背景进行精确配置。它强调“按明确规格生成”，而不是仅凭一句创意让 AI 自动完成全部内容。
主要能力
- 列出并预览数字人，选择 avatar_id 与默认 voice_id。
- 列出可用声音，按性别、语言等匹配数字人。
- 编写并组织脚本，每个场景围绕一个概念。
- 生成单场景或多场景视频，逐场景配置数字人、声音、脚本与背景。
- 支持纯色、图片、视频背景，文字叠加，自动字幕，模板与变量替换。
- 支持从照片创建数字人、生成透明 WebM、上传图片/音频/视频资源。
- 支持 Webhook、Remotion 集成、分辨率与宽高比设置、配额查看。
- 提供视频状态查询与下载，以及删除、列出账户视频等管理能力。
使用方式
所有请求需要 X-Api-Key 请求头，并设置 HEYGEN_API_KEY 环境变量。若环境中提供 HeyGen MCP 工具（mcp__heygen__*），优先使用它们查询视频状态、列出视频和删除视频；视频生成以及数字人、声音列表则通过直接 API 调用完成。
默认工作流：
- GET /v2/avatars 列出数字人，选择并预览，记录 avatar_id 和 default_voice_id。
- 如需要，GET /v2/voices 选择与数字人性别、语言匹配的声音。
- 按场景编写脚本，每个场景一个概念。
- POST /v2/video/generate，按场景配置数字人、声音、脚本和背景。
- GET /v2/videos/{video_id} 轮询直至状态为 completed。
认证示例：
curl -X GET "https://api.heygen.com/v2/avatars"
-H "X-Api-Key: $HEYGEN_API_KEY"
适用场景
适合需要指定某个数字人说指定台词、多场景搭配不同背景、生成用于合成的透明 WebM、使用特定声音朗读脚本、按精确规格批量生成视频等需求。如果用户只是描述一个视频想法并希望 AI 自动处理脚本、数字人和画面，应改用 create-video 技能。
限制与注意事项
- 视频生成通常需要 5–15 分钟甚至更久，应设置较宽松的超时。
- 开发阶段可设置 test: true 避免消耗额度，但输出会带水印。
- 生成前应验证数字人与声音 ID 存在；优先使用数字人的默认声音，无默认声音时手动匹配性别。
- 生成前建议下载 preview_image_url 供用户确认数字人形象。
- 额度与用量限制参见配额参考文档；具体计费与价格信息暂未提供。