虚拟人视频
使用 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__*),请优先使用它们,而不是直接进行 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 创建视频
此技能适用于精确控制——你选择虚拟人物,编写精确脚本,配置每个场景。
如果用户希望描述一个视频想法,让 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 是否存在