头像视频
使用 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__*),请优先使用它们——它们会自动处理身份验证和请求格式。
| 任务 | 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 |
| 设置 Webhooks | webhooks.md |
何时使用此技能与创建视频技能
此技能适用于精确控制——您选择头像、编写精确脚本、配置每个场景。
如果用户只想描述一个视频创意,而让 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 - 轮询模式和下载 URL
- references/assets.md - 上传图片、视频、音频
- references/dimensions.md - 分辨率和宽高比
- references/quota.md - 积分系统和使用限制
最佳实践
- 在生成前预览头像 — 下载
preview_image_url,以便用户在提交前查看头像 - 使用头像的默认语音 — 大多数头像都有预匹配的
default_voice_id,可带来自然效果 - 回退方案:手动匹配性别 — 如果没有默认语音,请确保头像和语音性别匹配
- 开发时使用测试模式 — 设置
test: true以避免消耗积分(输出将带有水印) - 设置较长的超时时间 — 视频生成通常需要 5-15 分钟,有时更长
- 验证输入 — 生成前检查头像和语音 ID 是否存在