Avatar Video
Generate HeyGen v3 avatar or photo-animated videos with exact avatar, voice, script, and background specs via API or MCP tools.
Overview
avatar-video is an agent skill most often used in Build (also Launch, Grow) that creates HeyGen v3 avatar or image-driven speaking videos with full API control.
Install
npx skills add https://github.com/heygen-com/skills --skill avatar-videoWhat is this skill?
- POST /v3/videos with discriminated type avatar (avatar_id) vs image (AssetInput / Avatar IV)
- X-Api-Key authentication via HEYGEN_API_KEY and preference for mcp__heygen__* tools when available
- Transparent background option with remove_background for compositing workflows
- Script-controlled speaking avatars for brand-consistent production batches
- Documented pairing with Remotion and batch generation with exact specs
- Two creation modes via type discriminator: avatar and image on POST /v3/videos
Adoption & trust: 995 installs on skills.sh; 279 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need repeatable AI presenter videos with fixed avatars, voices, and scripts but only have ad-hoc HeyGen UI clicks, not an API or MCP workflow.
Who is it for?
Indie builders automating product demos, course modules, or multilingual marketing cuts with HeyGen plus optional Remotion compositing.
Skip if: Teams without a HeyGen API key budget, or projects that only need static images without scripted video generation.
When should I use this skill?
Choosing avatars and voices, writing exact scripts, animating photos, transparent exports, Remotion pairing, or batch HeyGen generation with precise control.
What do I get? / Deliverables
You can submit v3 video jobs with avatar or image mode, transparent backgrounds when required, and batch-ready specs from your agent or backend.
- Submitted v3 video job with avatar or image mode
- Configured voice, script, and background (including transparent when needed)
- Repeatable API or MCP invocation pattern for batch runs
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Hooking HeyGen’s POST /v3/videos and auth is integration work done while building automated content or product pipelines. The skill centers on API/MCP integration, AssetInput for Avatar IV, and batch specs—not one-off manual editing.
Where it fits
Call POST /v3/videos from your SaaS after a user uploads a photo for Avatar IV onboarding.
Render launch-week explainers with fixed avatar_id and approved scripts for each landing page variant.
Batch localized voiceovers with the same avatar specs for email and social clips.
Prefer mcp__heygen__* tools in the agent to list avatars and submit jobs without hand-written curl each time.
How it compares
HeyGen API/MCP integration skill—not a generic prompt-only video chat skill or an on-device rendering pipeline.
Common Questions / FAQ
Who is avatar-video for?
Solo builders and small teams using Claude Code, Cursor, or similar agents to produce scripted HeyGen videos programmatically with brand-consistent avatars and voices.
When should I use avatar-video?
In Build while integrating HEYGEN_API_KEY into your app or agent; at Launch for distribution-ready explainers; in Grow when batching lifecycle or support video variants.
Is avatar-video safe to install?
It expects a paid API key and network calls to HeyGen; store secrets outside the repo and review the Security Audits panel on this page before enabling MCP tools.
SKILL.md
READMESKILL.md - Avatar Video
# Avatar Video Create AI avatar videos with full control over avatars, voices, scripts, and backgrounds using `POST /v3/videos`. Two creation modes via discriminated union on `type`: - `"type": "avatar"` + `avatar_id` — use a HeyGen avatar from the library - `"type": "image"` + `image` (AssetInput) — animate any photo via Avatar IV ## Authentication All requests require the `X-Api-Key` header. Set the `HEYGEN_API_KEY` environment variable. ```bash curl -X GET "https://api.heygen.com/v3/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 /v3/videos/{video_id}` | | List account videos | `mcp__heygen__list_videos` | `GET /v3/videos` | | Delete a video | `mcp__heygen__delete_video` | `DELETE /v3/videos/{video_id}` | Video generation (`POST /v3/videos`) and avatar/voice listing are done via direct API calls — see reference files below. ## Default Workflow 1. **List avatar looks** — `GET /v3/avatars/looks` → pick a look, note its `id` (this is the `avatar_id`) and `default_voice_id`. See [avatars.md](references/avatars.md) 2. **List voices** (if needed) — `GET /v3/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 /v3/videos` with `avatar_id`, `voice_id`, `script`, and optional `background` per scene. See [video-generation.md](references/video-generation.md) 5. **Poll for completion** — `GET /v3/videos/{video_id}` until status is `completed`. See [video-status.md](references/video-status.md) ## Routing: This Skill vs Create Video **This skill** = precise control (specific avatar, exact script, custom background). **create-video** = prompt-based ("make me a video about X", AI handles the rest). ## Reference Files Read these as needed — they contain endpoint details, request/response schemas, and code examples (curl, TypeScript, Python). **Core workflow:** - [references/video-generation.md](references/video-generation.md) — `POST /v3/videos` request fields, avatar input modes, voice settings, backgrounds - [references/avatars.md](references/avatars.md) — `GET /v3/avatars` (groups) and `GET /v3/avatars/looks` (looks → `avatar_id`) - [references/voices.md](references/voices.md) — `GET /v3/voices` with filtering by language, gender, engine - [references/video-status.md](references/video-status.md) — `GET /v3/videos/{id}` polling patterns and download **Customization:** - [references/scripts.md](references/scripts.md) — Script writing, SSML break tags, pacing - [references/backgrounds.md](references/backgrounds.md) — Solid color and image backgrounds - [references/captions.md](references/captions.md) — Auto-generated captions/subtitles - [references/text-overlays.md](refer