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_agentwith prompt and config (duration_sec, orientation, avatar_id)Call
mcp__heygen__get_videowith 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.mdGET /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 |
| 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