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.

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:

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) — use v3 endpoints from create-video or avatar-video skills:

1. Write an optimized prompt using prompt-optimizer.md → visual-styles.md
2. POST /v3/video-agents (replaces /v1/video_agent/generate) — see create-video skill
3. GET /v3/videos/ (replaces /v2/videos/) — 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