HeyGen API
AI avatar video creation API for generating talking-head videos, explainers, and presentations.
Default Workflow
Prefer Video Agent API (POST /v1/video_agent/generate) for most video requests.
Always use prompt-optimizer.md guidelines to structure prompts with scenes, timing, and visual styles.
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 | Read |
|---|---|
| Generate video from prompt (easy) | prompt-optimizer.md → video-agent.md |
| Generate video with precise control | video-generation.md, avatars.md, voices.md |
| Check video status / get download URL | video-status.md |
| Add captions or text overlays | captions.md, text-overlays.md |
| Transparent video for compositing | video-generation.md (WebM section) |
| Real-time interactive avatar | streaming-avatars.md |
| Translate/dub existing video | video-translation.md |
| 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
- •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/video-translation.md - Translating videos and dubbing
- •references/streaming-avatars.md - Real-time interactive sessions
- •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