HeyGen API 教程：AI 虚拟形象视频生成与弃用迁移指南

heygen by heygen-com/skills

1,000 周安装量

92 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/heygen-com/skills --skill heygen

AI/机器学习自动化 API

🇨🇳中文介绍

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`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

733,500 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

AI Elements：基于shadcn/ui的AI原生应用组件库，快速构建对话界面

50,500 周安装

AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具

40,200 周安装

任务	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/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 - 分辨率和宽高比

🇺🇸English

HeyGen API (Deprecated)

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.

Tool Selection

If HeyGen MCP tools are available (mcp__heygen__*), prefer them over direct HTTP API calls — they handle authentication and request formatting automatically.

Task	MCP Tool	Fallback (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.

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:

Write an optimized prompt using prompt-optimizer.md → visual-styles.md
Call mcp__heygen__generate_video_agent with prompt and config (duration_sec, orientation, avatar_id)
Call mcp__heygen__get_video with the returned video_id to poll status and get the download URL

Without MCP tools (direct API):

Write an optimized prompt using prompt-optimizer.md → visual-styles.md
POST /v1/video_agent/generate — see video-agent.md
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

Quick Reference

Task	MCP Tool	Read
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

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

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

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

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

Integration

references/remotion-integration.md - Using HeyGen in Remotion compositions

Weekly Installs

939

Repository

heygen-com/skills

GitHub Stars

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

claude-code865

opencode252

gemini-cli245

cursor234

codex232

github-copilot202

HeyGen API 教程：AI 虚拟形象视频生成与弃用迁移指南

🇨🇳中文介绍

HeyGen API (已弃用)

工具选择

相关 Skills

默认工作流程

快速参考

参考文件

基础

核心视频创作

视频定制

高级功能

集成