HeyGen API (Deprecated)
This skill is deprecated. Use the focused skills instead:
create-video — Generate videos from a text prompt (Video Agent API)
avatar-video — Build videos with specific avatars, voices, scripts, and scenes (v2 API)
This skill remains for backward compatibility but will be removed in a future release.
AI avatar video creation API for generating talking-head videos, explainers, and presentations.
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) |
| Generate video from prompt |
mcp__heygen__generate_video_agent |
POST /v1/video_agent/generate |
| 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} |
If no HeyGen MCP tools are available, use direct HTTP API calls with X-Api-Key: $HEYGEN_API_KEY header as documented in the reference files.
Default Workflow
Prefer Video Agent for most video requests.
Always use prompt-optimizer.md guidelines to structure prompts with scenes, timing, and visual styles.
With MCP tools:
- Write an optimized prompt using prompt-optimizer.md → visual-styles.md
- Call
mcp__heygen__generate_video_agent with prompt and config (duration_sec, orientation, avatar_id)
- Call
mcp__heygen__get_video with the returned video_id to poll status and get the download URL
Without MCP tools (direct API):
- Write an optimized prompt using prompt-optimizer.md → visual-styles.md
POST /v1/video_agent/generate — see video-agent.md
GET /v2/videos/<id> — see video-status.md
Only use v2/video/generate when user explicitly needs:
- Exact script without AI modification
- Specific voice_id selection
- Different avatars/backgrounds per scene
- Precise per-scene timing control
- Programmatic/batch generation with exact specs
Quick Reference
| Task |
MCP Tool |
Read |
| Generate video from prompt (easy) |
mcp__heygen__generate_video_agent |
prompt-optimizer.md → visual-styles.md → video-agent.md |
| Generate video with precise control |
— |
video-generation.md, avatars.md, voices.md |
| Check video status / get download URL |
mcp__heygen__get_video |
video-status.md |
| Add captions or text overlays |
— |
captions.md, text-overlays.md |
| Transparent video for compositing |
— |
video-generation.md (WebM section) |
| Use with Remotion |
— |
remotion-integration.md |
Reference Files
Foundation
- references/authentication.md - API key setup and X-Api-Key header
- references/quota.md - Credit system and usage limits
- references/video-status.md - Polling patterns and download URLs
- references/assets.md - Uploading images, videos, audio
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
- references/video-agent.md - One-shot prompt video generation
- references/prompt-optimizer.md - Writing effective Video Agent prompts (core workflow + rules)
- references/visual-styles.md - 20 named visual styles with full specs
- references/prompt-examples.md - Full production prompt example + ready-to-use templates
- references/dimensions.md - Resolution and aspect ratios
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
1---
2name: heygen
3description: |
4 [DEPRECATED] Use `create-video` for prompt-based video generation or `avatar-video` for precise avatar/scene control. This legacy skill combines both workflows — the newer focused skills provide clearer guidance.
5homepage: https://docs.heygen.com/reference/generate-video-agent
6allowed-tools: mcp__heygen__*
7metadata:
8 source: https://skillmd.com/skills/calesthio/heygen
9 openclaw:
10 requires:
11 env:
12 - HEYGEN_API_KEY
13 primaryEnv: HEYGEN_API_KEY
14---
15
16# HeyGen API (Deprecated)
17
18> **This skill is deprecated.** Use the focused skills instead:
19> - **`create-video`** — Generate videos from a text prompt (Video Agent API)
20> - **`avatar-video`** — Build videos with specific avatars, voices, scripts, and scenes (v2 API)
21
22This skill remains for backward compatibility but will be removed in a future release.
23
24---
25
26AI avatar video creation API for generating talking-head videos, explainers, and presentations.
27
28## Tool Selection
29
30If HeyGen MCP tools are available (`mcp__heygen__*`), **prefer them** over direct HTTP API calls — they handle authentication and request formatting automatically.
31
32| Task | MCP Tool | Fallback (Direct API) |
33|------|----------|----------------------|
34| Generate video from prompt | `mcp__heygen__generate_video_agent` | `POST /v1/video_agent/generate` |
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
39If no HeyGen MCP tools are available, use direct HTTP API calls with `X-Api-Key: $HEYGEN_API_KEY` header as documented in the reference files.
40
41## Default Workflow
42
43**Prefer Video Agent** for most video requests.
44Always use [prompt-optimizer.md](references/prompt-optimizer.md) guidelines to structure prompts with scenes, timing, and visual styles.
45
46**With MCP tools:**
471. Write an optimized prompt using [prompt-optimizer.md](references/prompt-optimizer.md) → [visual-styles.md](references/visual-styles.md)
482. Call `mcp__heygen__generate_video_agent` with prompt and config (duration_sec, orientation, avatar_id)
493. Call `mcp__heygen__get_video` with the returned video_id to poll status and get the download URL
50
51**Without MCP tools (direct API):**
521. Write an optimized prompt using [prompt-optimizer.md](references/prompt-optimizer.md) → [visual-styles.md](references/visual-styles.md)
532. `POST /v1/video_agent/generate` — see [video-agent.md](references/video-agent.md)
543. `GET /v2/videos/<id>` — see [video-status.md](references/video-status.md)
55
56Only use v2/video/generate when user explicitly needs:
57- Exact script without AI modification
58- Specific voice_id selection
59- Different avatars/backgrounds per scene
60- Precise per-scene timing control
61- Programmatic/batch generation with exact specs
62
63## Quick Reference
64
65| Task | MCP Tool | Read |
66|------|----------|------|
67| Generate video from prompt (easy) | `mcp__heygen__generate_video_agent` | [prompt-optimizer.md](references/prompt-optimizer.md) → [visual-styles.md](references/visual-styles.md) → [video-agent.md](references/video-agent.md) |
68| Generate video with precise control | — | [video-generation.md](references/video-generation.md), [avatars.md](references/avatars.md), [voices.md](references/voices.md) |
69| Check video status / get download URL | `mcp__heygen__get_video` | [video-status.md](references/video-status.md) |
70| Add captions or text overlays | — | [captions.md](references/captions.md), [text-overlays.md](references/text-overlays.md) |
71| Transparent video for compositing | — | [video-generation.md](references/video-generation.md) (WebM section) |
72| Use with Remotion | — | [remotion-integration.md](references/remotion-integration.md) |
73
74## Reference Files
75
76### Foundation
77- [references/authentication.md](references/authentication.md) - API key setup and X-Api-Key header
78- [references/quota.md](references/quota.md) - Credit system and usage limits
79- [references/video-status.md](references/video-status.md) - Polling patterns and download URLs
80- [references/assets.md](references/assets.md) - Uploading images, videos, audio
81
82### Core Video Creation
83- [references/avatars.md](references/avatars.md) - Listing avatars, styles, avatar_id selection
84- [references/voices.md](references/voices.md) - Listing voices, locales, speed/pitch
85- [references/scripts.md](references/scripts.md) - Writing scripts, pauses, pacing
86- [references/video-generation.md](references/video-generation.md) - POST /v2/video/generate and multi-scene videos
87- [references/video-agent.md](references/video-agent.md) - One-shot prompt video generation
88- [references/prompt-optimizer.md](references/prompt-optimizer.md) - Writing effective Video Agent prompts (core workflow + rules)
89- [references/visual-styles.md](references/visual-styles.md) - 20 named visual styles with full specs
90- [references/prompt-examples.md](references/prompt-examples.md) - Full production prompt example + ready-to-use templates
91- [references/dimensions.md](references/dimensions.md) - Resolution and aspect ratios
92
93### Video Customization
94- [references/backgrounds.md](references/backgrounds.md) - Solid colors, images, video backgrounds
95- [references/text-overlays.md](references/text-overlays.md) - Adding text with fonts and positioning
96- [references/captions.md](references/captions.md) - Auto-generated captions and subtitles
97
98### Advanced Features
99- [references/templates.md](references/templates.md) - Template listing and variable replacement
100- [references/photo-avatars.md](references/photo-avatars.md) - Creating avatars from photos
101- [references/webhooks.md](references/webhooks.md) - Webhook endpoints and events
102
103### Integration
104- [references/remotion-integration.md](references/remotion-integration.md) - Using HeyGen in Remotion compositions