Video Agent (Deprecated)

HeyGen API 技能用于 AI 数字人视频生成，但已被标记为弃用状态。官方推荐改用两个更专注的技能：create-video（基于提示词的视频代理 API）和 avatar-video（精确控制头像、声音、脚本、场景）。当前技能保留向后兼容性，将在未来版本移除。

核心用法：

• Video Agent 工作流（推荐）：使用优化提示词调用 mcp__heygen__generate_video_agent 生成视频，轮询 mcp__heygen__get_video 获取下载链接
• 精确控制工作流（v2 API）：仅在需要严格脚本控制、特定 voice_id、多场景精确时间等场景使用

显著优点：

• MCP 工具自动处理认证和请求格式
• 支持两种工作流：简单提示生成 vs 精确场景控制
• 提供 20 种命名视觉风格、字幕生成、透明背景 WebM 输出
• 完整的头像、声音、模板资源管理

局限性与风险：

• 技能已弃用，功能将被移除
• 需付费 HeyGen API 订阅和积分系统
• 视频生成需异步轮询，非即时返回
• 依赖第三方服务的可用性和配额限制

适合人群：需要批量生成数字人讲解视频、营销内容创作者、程序化视频生产开发者。

常规风险：API 密钥泄露、积分超额消费、生成内容版权争议、第三方服务稳定性依赖。

核心用法

HeyGen Skill 是一套完整的 AI 数字人视频生成 API 文档，支持两种主要工作流：

1. Video Agent（推荐）：通过自然语言提示一键生成视频，适合快速制作 talking-head 讲解视频、产品演示等。需遵循 prompt-optimizer.md 规范编写结构化提示词，指定场景、时长、视觉风格等要素。

2. v2 API（精确控制）：适用于需要严格脚本控制、特定声线选择、多场景不同 avatar/背景切换、精确时间轴编排的批量生产场景。

工具调用优先级：优先使用 MCP 工具（mcp__heygen__*），自动处理认证和请求格式化；无 MCP 时回退到直接 HTTP API 调用。

显著优点

• 官方文档来源：内容源自 HeyGen 官方 API 文档，结构完整，覆盖认证、配额、视频状态轮询、素材上传等全链路
• 安全最佳实践：API 密钥强制使用环境变量 HEYGEN_API_KEY，无硬编码风险
• MCP 原生支持：提供自动化工具封装，降低集成复杂度
• 丰富的视觉风格：内置 20 种命名视觉风格规范（visual-styles.md）
• 透明视频输出：支持 WebM 透明通道，便于后期合成

潜在缺点与局限性

• 已标记弃用：官方明确 deprecated，未来版本将移除，建议迁移至 create-video 和 avatar-video
• 商业服务依赖：需 HeyGen 付费账户，存在 API 配额和信用点数限制（quota.md）
• 视频生成异步：需要轮询状态获取最终下载 URL，非即时返回
• 无本地渲染：所有视频生成在云端完成，依赖网络稳定性和 HeyGen 服务可用性

适合人群

• 需要批量生成 AI 讲解视频的内容创作者、营销团队
• 构建自动化视频工作流的开发者（结合 Remotion 等工具）
• 企业培训、电商产品视频、多语言本地化视频制作场景

常规风险

• API 密钥泄露风险：若用户未按规范使用环境变量，存在密钥硬编码隐患
• 内容合规风险：AI 生成内容需遵守平台使用条款，避免生成误导性深度伪造内容
• 服务连续性：作为第三方 SaaS 依赖，存在服务变更、定价调整或地区访问限制的可能