📦 Avatar Video — AI虚拟人视频

使用 POST /v3/videos 全面控制虚拟形象、声音、脚本和背景，创建 AI 虚拟形象视频。通过 type 字段区分两种模式：

• "type": "avatar" + avatar_id —— 使用库中的 HeyGen 虚拟形象
• "type": "image" + image (AssetInput) —— 通过 Avatar IV 技术让任意照片说话

认证

所有请求需在 Header 中携带 X-Api-Key。请将 HEYGEN_API_KEY 环境变量设置好。

curl -X GET "https://api.heygen.com/v3/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

工具选择

如果 HeyGen MCP 工具可用（mcp__heygen__*），优先使用它们而非直接调用 HTTP API——它们会自动处理认证与请求格式。

默认工作流

• 列出虚拟形象外观 —— GET /v3/avatars/looks → 选择外观，记录其 id（即 avatar_id）与 default_voice_id。见 avatars.md
• 列出声音（如需） —— GET /v3/voices → 选择与虚拟形象性别/语言匹配的声音。见 voices.md
• 撰写脚本 —— 每段聚焦一个概念。见 scripts.md
• 生成视频 —— POST /v3/videos，传入 avatar_id、voice_id、script，以及每段可选的 background。见 video-generation.md
• 轮询完成 —— GET /v3/videos/{video_id} 直至状态为 completed。见 video-status.md

路由：本技能 vs Create Video

本技能 = 精确控制（指定虚拟形象、精确脚本、自定义背景）。 create-video = 基于提示（“帮我做一段关于 X 的视频”，AI 全权处理）。

参考文件

按需阅读——内含端点详情、请求/响应结构及示例（curl、TypeScript、Python）。

核心工作流：

• references/video-generation.md —— POST /v3/videos 请求字段、虚拟形象输入模式、声音设置、背景
• references/avatars.md —— GET /v3/avatars（分组）与 GET /v3/avatars/looks（外观 → avatar_id）
• references/voices.md —— GET /v3/voices，可按语言、性别、引擎筛选
• references/video-status.md —— GET /v3/videos/{id} 轮询模式与下载

自定义：

• references/scripts.md —— 脚本撰写、SSML 停顿标签、语速
• references/backgrounds.md —— 纯色与图片背景
• references/captions.md —— 自动生成字幕/标题
• references/text-overlays.md —— 带字体与定位的文字叠加

高级：

• references/photo-avatars.md —— 通过 type: "image"（Avatar IV）让照片说话、AI 生成虚拟形象
• references/templates.md —— 模板列表与变量替换
• references/remotion-integration.md —— 在 Remotion 合成中使用 HeyGen 虚拟形象
• references/webhooks.md —— Webhook 端点与事件
• references/assets.md —— 上传图片、视频、音频
• references/dimensions.md —— 分辨率与宽高比
• references/quota.md —— 积分系统与用量上限

最佳实践

• 生成前先预览虚拟形象 —— 调用 GET /v3/avatars/looks 并下载 preview_image_url，让用户确认
• 优先使用虚拟形象默认声音 —— 多数虚拟形象已配 default_voice_id，效果更自然
• 备选：手动匹配性别 —— 若无默认声音，确保虚拟形象与声音性别一致
• 开发阶段使用测试模式 —— 设置 test: true 避免消耗积分（输出带水印）
• 设置足够长的超时 —— 视频生成通常需 5–15 分钟，有时更长
• 校验输入 —— 生成前确认虚拟形象与声音 ID 存在