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/
— 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
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
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