虚拟主播视频
使用 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 |
| 设置 Webhooks | 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 是否存在