HeyGen API (Deprecated)
This skill is deprecated. Use the focused skills instead:
create-video
— Generate videos from a text prompt (Video Agent API, POST /v3/video-agents
)avatar-video
— Build videos with specific avatars, voices, scripts, and scenes (v3 API, POST /v3/videos
)
Warning: The endpoints documented below are v1/v2 and deprecated. The replacement skills above use the current v3 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 | Deprecated Endpoint | v3 Replacement |
|---|
| Generate video from prompt | mcp__heygen__generate_video_agent
| POST /v1/video_agent/generate
| POST /v3/video-agents
|
| Check video status / get URL | mcp__heygen__get_video
| GET /v2/videos/{video_id}
| GET /v3/videos/{video_id}
|
| List account videos | mcp__heygen__list_videos
| GET /v2/videos
| GET /v3/videos
|
| Delete a video | mcp__heygen__delete_video
| DELETE /v2/videos/{video_id}
| DELETE /v3/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) — use v3 endpoints from create-video
or avatar-video
skills:
- Write an optimized prompt using prompt-optimizer.md → visual-styles.md
POST /v3/video-agents
(replaces /v1/video_agent/generate
) — see create-video
skillGET /v3/videos/<id>
(replaces /v2/videos/<id>
) — see create-video
skill
Only use the direct video API (now
POST /v3/videos
, formerly
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
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 - Video generation and multi-scene videos (uses deprecated v2 endpoint — see
avatar-video
skill for v3)
- 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
