SKILL.md
Create Video
Generate complete videos from a text prompt. Describe what you want and the AI handles script writing, avatar selection, visuals, voiceover, pacing, and captions automatically.
Authentication
All requests require the X-Api-Key header. Set the HEYGENAPIKEY environment variable.
curl -X POST "https://api.heygen.com/v1/video_agent/generate" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Create a 60-second product demo video."}'
Tool Selection
If HeyGen MCP tools are available (mcpheygen*), prefer them over direct HTTP API calls — they handle authentication and request formatting automatically.
| Task | MCP Tool | Fallback (Direct API) |
|---|---|---|
| Generate video from prompt | mcpheygengeneratevideoagent |
POST /v1/video_agent/generate |
| Check video status / get URL | mcpheygenget_video |
GET /v2/videos/{video_id} |
| List account videos | mcpheygenlist_videos |
GET /v2/videos |
| Delete a video | mcpheygendelete_video |
DELETE /v2/videos/{video_id} |
If no HeyGen MCP tools are available, use direct HTTP API calls as documented in the reference files.
Default Workflow
Always use [prompt-optimizer.md](references/prompt-optimizer.md) guidelines to structure prompts with scenes, timing, and visual styles.
With MCP tools:
- Write an optimized prompt using [prompt-optimizer.md](references/prompt-optimizer.md) → [visual-styles.md](references/visual-styles.md)
- Call
mcpheygengeneratevideoagentwith prompt and config (durationsec, orientation, avatarid) - Call
mcpheygengetvideowith the returned videoid to poll status and get the download URL
Without MCP tools (direct API):
- Write an optimized prompt using [prompt-optimizer.md](references/prompt-optimizer.md) → [visual-styles.md](references/visual-styles.md)
POST /v1/video_agent/generate— see [video-agent.md](references/video-agent.md)GET /v2/videos/<id>— see [video-status.md](references/video-status.md)
Quick Reference
| Task | MCP Tool | Read |
|---|---|---|
| Generate video from prompt | mcpheygengeneratevideoagent |
[prompt-optimizer.md](references/prompt-optimizer.md) → [visual-styles.md](references/visual-styles.md) → [video-agent.md](references/video-agent.md) |
| Check video status / get download URL | mcpheygenget_video |
[video-status.md](references/video-status.md) |
| Upload reference files for prompt | — | [assets.md](references/assets.md) |
When to Use This Skill vs Avatar Video
This skill is for prompt-based video creation — describe what you want, and the AI handles the rest.
If the user needs precise control over specific avatars, exact scripts, per-scene voice/background configuration, or multi-scene composition, use the avatar-video skill instead.
| User Says | This Skill | Avatar Video 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" | ✓ |
Reference Files
Core Workflow
- [references/prompt-optimizer.md](references/prompt-optimizer.md) - Writing effective prompts (core workflow + rules)
- [references/visual-styles.md](references/visual-styles.md) - 20 named visual styles with full specs
- [references/prompt-examples.md](references/prompt-examples.md) - Full production prompt example + ready-to-use templates
- [references/video-agent.md](references/video-agent.md) - Video Agent API endpoint details
Foundation
- [references/video-status.md](references/video-status.md) - Polling patterns and download URLs
- [references/webhooks.md](references/webhooks.md) - Webhook endpoints and events
- [references/assets.md](references/assets.md) - Uploading images, videos, audio as references
- [references/dimensions.md](references/dimensions.md) - Resolution and aspect ratios
- [references/quota.md](references/quota.md) - Credit system and usage limits
Best Practices
- Optimize your prompt — The difference between mediocre and professional results depends entirely on prompt quality. Always use the prompt optimizer
- Specify duration — Use
config.duration_secfor predictable length - Lock avatar if needed — Use
config.avatar_idfor consistency across videos - Upload reference files — Help the agent understand your brand/product
- Iterate on prompts — Refine based on results; Video Agent is great for quick iterations