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
HEYGEN_API_KEY
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 (
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 as documented in the reference files.
Default Workflow
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/
— see
video-status.md
Quick Reference
Task
MCP Tool
Read
Generate video from prompt
mcp__heygen__generate_video_agent
prompt-optimizer.md
→
visual-styles.md
→
video-agent.md
Check video status / get download URL
mcp__heygen__get_video
video-status.md
Upload reference files for prompt
—
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
- Writing effective 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/video-agent.md
- Video Agent API endpoint details
Foundation
references/video-status.md
- Polling patterns and download URLs
references/webhooks.md
- Webhook endpoints and events
references/assets.md
- Uploading images, videos, audio as references
references/dimensions.md
- Resolution and aspect ratios
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_sec
for predictable length
Lock avatar if needed
— Use
config.avatar_id
for 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