Avatar Video

Create AI avatar videos with full control over avatars, voices, scripts, scenes, and backgrounds. Build single or multi-scene videos with exact configuration using HeyGen's /v2/video/generate API.

Authentication

All requests require the X-Api-Key header. Set the HEYGEN_API_KEY environment variable.

curl -X GET "https://api.heygen.com/v2/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

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)
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}

Video generation (POST /v2/video/generate) and avatar/voice listing are done via direct API calls, see reference files below.

Default Workflow

1. List avatars, GET /v2/avatars → pick an avatar, preview it, note avatar_id and default_voice_id. See avatars.md
2. List voices (if needed), GET /v2/voices → pick a voice matching the avatar's gender/language. See voices.md
3. Write the script, Structure scenes with one concept each. See scripts.md
4. Generate the video, POST /v2/video/generate with avatar, voice, script, and background per scene. See video-generation.md
5. Poll for completion, GET /v2/videos/{video_id} until status is completed. See video-status.md

Quick Reference