create-video

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/<id> — 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

Weekly Installs282Repositoryheygen-com/skillsGitHub Stars91First Seen10 days agoSecurity AuditsGen Agent Trust HubPassSocketPassSnykWarnInstalled onclaude-code272codex37cline35gemini-cli35kimi-cli35cursor35