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
- List avatars —
GET /v2/avatars → pick an avatar, preview it, note avatar_id and default_voice_id. See avatars.md
- List voices (if needed) —
GET /v2/voices → pick a voice matching the avatar's gender/language. See voices.md
- Write the script — Structure scenes with one concept each. See scripts.md
- Generate the video —
POST /v2/video/generate with avatar, voice, script, and background per scene. See video-generation.md
- Poll for completion —
GET /v2/videos/{video_id} until status is completed. See video-status.md
Quick Reference
| Task |
Read |
| List and preview avatars |
avatars.md |
| List and select voices |
voices.md |
| Write and structure scripts |
scripts.md |
| Generate video (single or multi-scene) |
video-generation.md |
| Add custom backgrounds |
backgrounds.md |
| Add captions / subtitles |
captions.md |
| Add text overlays |
text-overlays.md |
| Create transparent WebM video |
video-generation.md (WebM section) |
| Use templates |
templates.md |
| Create avatar from photo |
photo-avatars.md |
| Check video status / download |
video-status.md |
| Upload assets (images, audio) |
assets.md |
| Use with Remotion |
remotion-integration.md |
| Set up webhooks |
webhooks.md |
When to Use This Skill vs Create Video
This skill is for precise control — you choose the avatar, write the exact script, configure each scene.
If the user just wants to describe a video idea and let AI handle the rest (script, avatar, visuals), use the create-video skill instead.
| User Says |
Create Video Skill |
This Skill |
| "Make me a video about X" |
✓ |
|
| "Create a product demo" |
✓ |
|
| "I want avatar Y to say exactly Z" |
|
✓ |
| "Multi-scene video with different backgrounds" |
|
✓ |
| "Transparent WebM for compositing" |
|
✓ |
| "Use this specific voice for my script" |
|
✓ |
| "Batch generate videos with exact specs" |
|
✓ |
Reference Files
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
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
Foundation
- references/video-status.md - Polling patterns and download URLs
- references/assets.md - Uploading images, videos, audio
- references/dimensions.md - Resolution and aspect ratios
- references/quota.md - Credit system and usage limits
Best Practices
- Preview avatars before generating — Download
preview_image_url so the user can see the avatar before committing
- Use avatar's default voice — Most avatars have a
default_voice_id pre-matched for natural results
- Fallback: match gender manually — If no default voice, ensure avatar and voice genders match
- Use test mode for development — Set
test: true to avoid consuming credits (output will be watermarked)
- Set generous timeouts — Video generation often takes 5-15 minutes, sometimes longer
- Validate inputs — Check avatar and voice IDs exist before generating
1---
2name: avatar-video
3description: |
4 Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.
5homepage: https://docs.heygen.com/reference/create-a-video
6allowed-tools: mcp__heygen__*
7metadata:
8 source: https://skillmd.com/skills/calesthio/avatar-video
9 openclaw:
10 requires:
11 env:
12 - HEYGEN_API_KEY
13 primaryEnv: HEYGEN_API_KEY
14---
15
16# Avatar Video
17
18Create 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.
19
20## Authentication
21
22All requests require the `X-Api-Key` header. Set the `HEYGEN_API_KEY` environment variable.
23
24```bash
25curl -X GET "https://api.heygen.com/v2/avatars" \
26 -H "X-Api-Key: $HEYGEN_API_KEY"
27```
28
29## Tool Selection
30
31If HeyGen MCP tools are available (`mcp__heygen__*`), **prefer them** over direct HTTP API calls — they handle authentication and request formatting automatically.
32
33| Task | MCP Tool | Fallback (Direct API) |
34|------|----------|----------------------|
35| Check video status / get URL | `mcp__heygen__get_video` | `GET /v2/videos/{video_id}` |
36| List account videos | `mcp__heygen__list_videos` | `GET /v2/videos` |
37| Delete a video | `mcp__heygen__delete_video` | `DELETE /v2/videos/{video_id}` |
38
39Video generation (`POST /v2/video/generate`) and avatar/voice listing are done via direct API calls — see reference files below.
40
41## Default Workflow
42
431. **List avatars** — `GET /v2/avatars` → pick an avatar, preview it, note `avatar_id` and `default_voice_id`. See [avatars.md](references/avatars.md)
442. **List voices** (if needed) — `GET /v2/voices` → pick a voice matching the avatar's gender/language. See [voices.md](references/voices.md)
453. **Write the script** — Structure scenes with one concept each. See [scripts.md](references/scripts.md)
464. **Generate the video** — `POST /v2/video/generate` with avatar, voice, script, and background per scene. See [video-generation.md](references/video-generation.md)
475. **Poll for completion** — `GET /v2/videos/{video_id}` until status is `completed`. See [video-status.md](references/video-status.md)
48
49## Quick Reference
50
51| Task | Read |
52|------|------|
53| List and preview avatars | [avatars.md](references/avatars.md) |
54| List and select voices | [voices.md](references/voices.md) |
55| Write and structure scripts | [scripts.md](references/scripts.md) |
56| Generate video (single or multi-scene) | [video-generation.md](references/video-generation.md) |
57| Add custom backgrounds | [backgrounds.md](references/backgrounds.md) |
58| Add captions / subtitles | [captions.md](references/captions.md) |
59| Add text overlays | [text-overlays.md](references/text-overlays.md) |
60| Create transparent WebM video | [video-generation.md](references/video-generation.md) (WebM section) |
61| Use templates | [templates.md](references/templates.md) |
62| Create avatar from photo | [photo-avatars.md](references/photo-avatars.md) |
63| Check video status / download | [video-status.md](references/video-status.md) |
64| Upload assets (images, audio) | [assets.md](references/assets.md) |
65| Use with Remotion | [remotion-integration.md](references/remotion-integration.md) |
66| Set up webhooks | [webhooks.md](references/webhooks.md) |
67
68## When to Use This Skill vs Create Video
69
70This skill is for **precise control** — you choose the avatar, write the exact script, configure each scene.
71
72If the user just wants to **describe a video idea** and let AI handle the rest (script, avatar, visuals), use the **create-video** skill instead.
73
74| User Says | Create Video Skill | This Skill |
75|-----------|:------------------:|:----------:|
76| "Make me a video about X" | ✓ | |
77| "Create a product demo" | ✓ | |
78| "I want avatar Y to say exactly Z" | | ✓ |
79| "Multi-scene video with different backgrounds" | | ✓ |
80| "Transparent WebM for compositing" | | ✓ |
81| "Use this specific voice for my script" | | ✓ |
82| "Batch generate videos with exact specs" | | ✓ |
83
84## Reference Files
85
86### Core Video Creation
87- [references/avatars.md](references/avatars.md) - Listing avatars, styles, avatar_id selection
88- [references/voices.md](references/voices.md) - Listing voices, locales, speed/pitch
89- [references/scripts.md](references/scripts.md) - Writing scripts, pauses, pacing
90- [references/video-generation.md](references/video-generation.md) - POST /v2/video/generate and multi-scene videos
91
92### Video Customization
93- [references/backgrounds.md](references/backgrounds.md) - Solid colors, images, video backgrounds
94- [references/text-overlays.md](references/text-overlays.md) - Adding text with fonts and positioning
95- [references/captions.md](references/captions.md) - Auto-generated captions and subtitles
96
97### Advanced Features
98- [references/templates.md](references/templates.md) - Template listing and variable replacement
99- [references/photo-avatars.md](references/photo-avatars.md) - Creating avatars from photos
100- [references/webhooks.md](references/webhooks.md) - Webhook endpoints and events
101
102### Integration
103- [references/remotion-integration.md](references/remotion-integration.md) - Using HeyGen in Remotion compositions
104
105### Foundation
106- [references/video-status.md](references/video-status.md) - Polling patterns and download URLs
107- [references/assets.md](references/assets.md) - Uploading images, videos, audio
108- [references/dimensions.md](references/dimensions.md) - Resolution and aspect ratios
109- [references/quota.md](references/quota.md) - Credit system and usage limits
110
111## Best Practices
112
1131. **Preview avatars before generating** — Download `preview_image_url` so the user can see the avatar before committing
1142. **Use avatar's default voice** — Most avatars have a `default_voice_id` pre-matched for natural results
1153. **Fallback: match gender manually** — If no default voice, ensure avatar and voice genders match
1164. **Use test mode for development** — Set `test: true` to avoid consuming credits (output will be watermarked)
1175. **Set generous timeouts** — Video generation often takes 5-15 minutes, sometimes longer
1186. **Validate inputs** — Check avatar and voice IDs exist before generating