# HeyGen Avatar Video

Makes avatar videos with chosen avatars, voices, scripts and per-scene backgrounds.

- Repository: https://github.com/calesthio/OpenMontage (74341 stars)
- Category: Media
- License: AGPL-3.0
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add calesthio/OpenMontage --skill avatar-video -g -a claude-code -y`
Codex: `npx skills add calesthio/OpenMontage --skill avatar-video -g -a codex -y`
Cursor: `npx skills add calesthio/OpenMontage --skill avatar-video -g -a cursor -y`
Gemini CLI: `npx skills add calesthio/OpenMontage --skill avatar-video -g -a gemini-cli -y`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.

```bash
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](references/avatars.md)
2. **List voices** (if needed), `GET /v2/voices` → pick a voice matching the avatar's gender/language. See [voices.md](references/voices.md)
3. **Write the script**, Structure scenes with one concept each. See [scripts.md](references/scripts.md)
4. **Generate the video**, `POST /v2/video/generate` with avatar, voice, script, and background per scene. See [video-generation.md](references/video-generation.md)
5. **Poll for completion**, `GET /v2/videos/{video_id}` until status is `completed`. See [video-status.md](references/video-status.md)

## Quick Reference

The rest: https://github.com/calesthio/OpenMontage/blob/HEAD/.agents/skills/avatar-video/SKILL.md