虚拟人视频
创建AI虚拟人视频,完全控制虚拟人、语音、脚本、场景和背景。使用HeyGen的/v2/video/generate API构建具有精确配置的单场或多场视频。
认证
所有请求都需要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处理其余部分(脚本、虚拟人、视觉效果),请改用创建视频技能。
| 用户说 | 创建视频技能 | 此技能 |
|---|---|---|
| “给我做一个关于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是否存在