Back to Details

heygen

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HeyGen API (Deprecated)

HeyGen API（已废弃）

This skill is deprecated. Use the focused skills instead:
  • create-video
     — Generate videos from a text prompt (Video Agent API)
  • avatar-video
     — Build videos with specific avatars, voices, scripts, and scenes (v2 API)
This skill remains for backward compatibility but will be removed in a future release.
AI avatar video creation API for generating talking-head videos, explainers, and presentations.
此技能已废弃，请改用以下专项技能：
  • create-video
     — 基于文本提示词生成视频（Video Agent API）
  • avatar-video
     — 使用指定虚拟形象、语音、脚本和场景制作视频（v2 API）
此技能仅为保持向后兼容性而保留，未来版本中将被移除。
用于生成虚拟人解说视频、讲解视频和演示视频的AI虚拟人视频创建API。

Tool Selection

工具选择

If HeyGen MCP tools are available (
mcp__heygen__*
), prefer them over direct HTTP API calls — they handle authentication and request formatting automatically.
TaskMCP ToolFallback (Direct API)
Generate video from prompt
mcp__heygen__generate_video_agent
POST /v1/video_agent/generate
Check video status / get URL
mcp__heygen__get_video
GET /v2/videos/{video_id}
List account videos
mcp__heygen__list_videos
GET /v2/videos
Delete a video
mcp__heygen__delete_video
DELETE /v2/videos/{video_id}
If no HeyGen MCP tools are available, use direct HTTP API calls with 
X-Api-Key: $HEYGEN_API_KEY
header as documented in the reference files.
如果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工具，请按照参考文档中的说明，使用带有
X-Api-Key: $HEYGEN_API_KEY
请求头的方式直接调用HTTP API。

Default Workflow

默认工作流

Prefer Video Agent for most video requests. Always use prompt-optimizer.md guidelines to structure prompts with scenes, timing, and visual styles.
With MCP tools:
  1. Write an optimized prompt using prompt-optimizer.md → visual-styles.md
  2. Call 
    mcp__heygen__generate_video_agent
    with prompt and config (duration_sec, orientation, avatar_id)
  3. Call 
    mcp__heygen__get_video
    with the returned video_id to poll status and get the download URL
Without MCP tools (direct API):
  1. Write an optimized prompt using prompt-optimizer.md → visual-styles.md
  2. POST /v1/video_agent/generate
    — see video-agent.md
  3. GET /v2/videos/<id>
    — see video-status.md
Only use v2/video/generate when user explicitly needs:
  • Exact script without AI modification
  • Specific voice_id selection
  • Different avatars/backgrounds per scene
  • Precise per-scene timing control
  • Programmatic/batch generation with exact specs
大多数视频请求优先使用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
  • 每个场景使用不同的虚拟形象/背景
  • 精准控制每个场景的时长
  • 按精确规格进行程序化/批量生成

Quick Reference

快速参考

TaskMCP ToolRead
Generate video from prompt (easy)
mcp__heygen__generate_video_agent
prompt-optimizer.md → visual-styles.md → video-agent.md
Generate video with precise control—video-generation.md, avatars.md, voices.md
Check video status / get download URL
mcp__heygen__get_video
video-status.md
Add captions or text overlays—captions.md, text-overlays.md
Transparent video for compositing—video-generation.md (WebM section)
Use with Remotion—remotion-integration.md
任务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

Reference Files

参考文件

Foundation

基础部分

  • references/authentication.md - API key setup and X-Api-Key header
  • references/quota.md - Credit system and usage limits
  • references/video-status.md - Polling patterns and download URLs
  • references/assets.md - Uploading images, videos, audio
  • references/authentication.md - API密钥设置与X-Api-Key请求头
  • references/quota.md - 积分体系与使用限制
  • references/video-status.md - 轮询模式与下载URL
  • references/assets.md - 上传图片、视频、音频

Core Video Creation

核心视频创建

  • references/avatars.md - Listing avatars, styles, avatar_id selection
  • references/voices.md - Listing voices, locales, speed/pitch
  • references/scripts.md - Writing scripts, pauses, pacing
  • references/video-generation.md - POST /v2/video/generate and multi-scene videos
  • references/video-agent.md - One-shot prompt video generation
  • references/prompt-optimizer.md - Writing effective Video Agent prompts (core workflow + rules)
  • references/visual-styles.md - 20 named visual styles with full specs
  • references/prompt-examples.md - Full production prompt example + ready-to-use templates
  • references/dimensions.md - Resolution and aspect ratios
  • 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 - 分辨率与宽高比

Video Customization

视频定制

  • references/backgrounds.md - Solid colors, images, video backgrounds
  • references/text-overlays.md - Adding text with fonts and positioning
  • references/captions.md - Auto-generated captions and subtitles
  • references/backgrounds.md - 纯色、图片、视频背景
  • references/text-overlays.md - 添加带字体和位置设置的文本
  • references/captions.md - 自动生成字幕与副标题

Advanced Features

高级功能

  • references/templates.md - Template listing and variable replacement
  • references/photo-avatars.md - Creating avatars from photos
  • references/webhooks.md - Webhook endpoints and events
  • references/templates.md - 模板列表与变量替换
  • references/photo-avatars.md - 从照片创建虚拟形象
  • references/webhooks.md - Webhook端点与事件

Integration

集成部分

  • references/remotion-integration.md - Using HeyGen in Remotion compositions
  • references/remotion-integration.md - 在Remotion合成中使用HeyGen