heygen

HeyGen API（已弃用）

此技能已弃用。 请改用专用技能：

• create-video — 根据文本提示生成视频（Video Agent API）
• avatar-video — 使用指定的虚拟形象、声音、脚本和场景制作视频（v2 API）

此技能仍为向后兼容而保留，但将在未来版本中移除。

---

用于创建 AI 虚拟形象视频的 API，可生成真人讲解视频、解说视频和演示视频。

工具选择

如果有可用的 HeyGen MCP 工具（mcp__heygen__*），优先使用它们，而非直接调用 HTTP API——这些工具会自动处理身份验证和请求格式。

任务	MCP 工具	备用方案（直接 API）
根据提示生成视频	mcp__heygen__generate_video_agent	POST /v1/video_agent/generate
检查视频状态 / 获取 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}

如果没有可用的 HeyGen MCP 工具，请使用直接 HTTP API 调用，并按参考文件中的说明在请求头中加入 X-Api-Key: $HEYGEN_API_KEY。

默认工作流

对于大多数视频请求，优先使用 Video Agent。 始终遵循 prompt-optimizer.md 中的指南，用场景、时间安排和视觉风格来组织提示词。

使用 MCP 工具时：

1. 按照 prompt-optimizer.md → visual-styles.md 编写优化后的提示词
2. 使用提示词和配置（duration_sec、orientation、avatar_id）调用 mcp__heygen__generate_video_agent
3. 使用返回的 video_id 调用 mcp__heygen__get_video，轮询状态并获取下载 URL

不使用 MCP 工具（直接调用 API）时：

1. 按照 prompt-optimizer.md → visual-styles.md 编写优化后的提示词
2. POST /v1/video_agent/generate — 参见 video-agent.md
3. GET /v2/videos/<id> — 参见 video-status.md

仅在用户明确需要以下功能时使用 v2/video/generate：

• 使用未经 AI 修改的精确脚本
• 指定 voice_id
• 每个场景使用不同的虚拟形象 / 背景
• 精确控制每个场景的时间安排
• 按精确规格进行程序化 / 批量生成

快速参考

任务	MCP 工具	阅读
根据提示生成视频（简易）	mcp__heygen__generate_video_agent	prompt-optimizer.md → visual-styles.md → video-agent.md
精确控制视频生成	—	video-generation.md、avatars.md、voices.md
检查视频状态 / 获取下载 URL	mcp__heygen__get_video	video-status.md
添加字幕或文本叠加层	—	captions.md、text-overlays.md
用于合成的透明视频	—	video-generation.md（WebM 部分）
与 Remotion 搭配使用	—	remotion-integration.md

参考文件

基础

• references/authentication.md - API 密钥设置和 X-Api-Key 请求头
• references/quota.md - 积分系统和使用限额
• references/video-status.md - 轮询模式和下载 URL
• references/assets.md - 上传图像、视频和音频

核心视频创作

• references/avatars.md - 查看头像、风格并选择 avatar_id
• references/voices.md - 查看语音、语言区域、语速和音调
• references/scripts.md - 编写脚本、设置停顿和节奏
• references/video-generation.md - POST /v2/video/generate 和多场景视频
• references/video-agent.md - 通过单次提示词生成视频
• references/prompt-optimizer.md - 编写有效的 Video Agent 提示词（核心工作流和规则）
• references/visual-styles.md - 20 种命名视觉风格的完整规格
• references/prompt-examples.md - 完整的制作提示词示例和可直接使用的模板
• references/dimensions.md - 分辨率和宽高比

视频自定义

• 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