OpenMontage avatar-video

install

source · Clone the upstream repo

git clone https://github.com/calesthio/OpenMontage

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/calesthio/OpenMontage "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/avatar-video" ~/.claude/skills/calesthio-openmontage-avatar-video && rm -rf "$T"

manifest: .agents/skills/avatar-video/SKILL.md

source content

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