avatar-video

Avatar 视频

通过全面控制虚拟形象、语音、脚本、场景和背景，创建 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 完成——请参阅下方的参考文件。

默认工作流

1. 列出虚拟形象 — GET /v2/avatars → 选择一个虚拟形象，预览并记下 avatar_id 和 default_voice_id。请参阅 avatars.md
2. 列出语音（如有需要）— GET /v2/voices → 选择与虚拟形象的性别 / 语言相符的语音。请参阅 voices.md
3. 编写脚本 — 将场景组织成每个场景一个概念。请参阅 scripts.md
4. 生成视频 — 调用 POST /v2/video/generate，为每个场景配置虚拟形象、语音、脚本和背景。请参阅 video-generation.md
5. 轮询直至完成 — 持续调用 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

何时使用此技能，何时使用 Create Video

此技能适用于需要精确控制的场景——由你选择虚拟形象、编写确切的脚本并配置每个场景。

如果用户只是想描述一个视频构想，让 AI 处理其余内容（脚本、虚拟形象、视觉效果），请改用 create-video 技能。

用户说	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 - 积分系统和使用限额

最佳实践

1. 生成前预览虚拟形象 — 下载 preview_image_url，让用户在确认前查看虚拟形象
2. 使用虚拟形象的默认语音 — 大多数虚拟形象都有预先匹配、效果自然的 default_voice_id
3. 备用方案：手动匹配性别 — 如果没有默认语音，请确保虚拟形象和语音的性别匹配
4. 开发时使用测试模式 — 设置 test: true，避免消耗积分（输出会带有水印）
5. 设置充足的超时时间 — 视频生成通常需要 5-15 分钟，有时更久
6. 验证输入 — 生成前检查虚拟形象 ID 和语音 ID 是否存在