avatar-video

Avatar 视频

使用 POST /v3/videos 创建 AI Avatar 视频，并全面控制 Avatar、语音、脚本和背景。通过 type 上的判别联合支持两种创建模式：

• "type": "avatar" + avatar_id — 使用库中的 HeyGen Avatar
• "type": "image" + image (AssetInput) — 通过 Avatar IV 为任意照片添加动画

身份验证

所有请求都需要 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 — 它们会自动处理身份验证和请求格式。

任务	MCP 工具	备用方案（直接 API）
检查视频状态 / 获取 URL	mcp__heygen__get_video	GET /v3/videos/{video_id}
列出账户视频	mcp__heygen__list_videos	GET /v3/videos
删除视频	mcp__heygen__delete_video	DELETE /v3/videos/{video_id}

视频生成（POST /v3/videos）以及 Avatar/语音列表查询需通过直接 API 调用完成 — 请参阅下方的参考文件。

默认工作流

1. 列出 Avatar 外观 — GET /v3/avatars/looks → 选择一种外观，记下其 id（即 avatar_id）和 default_voice_id。请参阅 avatars.md
2. 列出语音（如有需要）— GET /v3/voices → 选择与 Avatar 的性别/语言匹配的语音。请参阅 voices.md
3. 编写脚本 — 将场景划分为各自包含一个概念的结构。请参阅 scripts.md
4. 生成视频 — 调用 POST /v3/videos，传入 avatar_id、voice_id、script，并可为每个场景设置可选的 background。请参阅 video-generation.md
5. 轮询直至完成 — 持续调用 GET /v3/videos/{video_id}，直到状态为 completed。请参阅 video-status.md

路由：此技能与 Create Video

此技能 = 精确控制（指定 Avatar、准确脚本、自定义背景）。 create-video = 基于提示词（“为我制作一个关于 X 的视频”，由 AI 处理其余部分）。

参考文件

按需阅读 — 文件中包含端点详情、请求/响应架构和代码示例（curl、TypeScript、Python）。

核心工作流：

• references/video-generation.md — POST /v3/videos 请求字段、Avatar 输入模式、语音设置、背景
• 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 生成的 Avatar
• references/templates.md — 模板列表和变量替换
• references/remotion-integration.md — 在 Remotion 合成中使用 HeyGen Avatar
• references/webhooks.md — Webhook 端点和事件
• references/assets.md — 上传图片、视频和音频
• references/dimensions.md — 分辨率和宽高比
• references/quota.md — 积分系统和使用限额

最佳实践

1. 生成前预览头像 — 使用 GET /v3/avatars/looks 并下载 preview_image_url，让用户在确认前查看头像
2. 使用头像的默认语音 — 大多数头像都有预先匹配的 default_voice_id，可获得自然的效果
3. 回退方案：手动匹配性别 — 如果没有默认语音，请确保头像和语音的性别一致
4. 开发时使用测试模式 — 设置 test: true，避免消耗额度（输出会带水印）
5. 设置较长的超时时间 — 视频生成通常需要 5-15 分钟，有时会更久
6. 验证输入 — 生成前检查头像和语音 ID 是否存在