Skip to main content

Documentation Index

Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

HeyGen offers two ways to create videos programmatically. The right choice depends on how much control you need.
Video AgentDirect Video
EndpointPOST /v3/video-agentsPOST /v3/videos
InputNatural language promptStructured JSON
Script writingAgent writes itYou write it
Avatar selectionAgent picks (or you override)You specify
Voice selectionAgent picks (or you override)You specify
Interactive iteration✅ Via chat mode❌
Webhook support✅ callback_url✅ callback_url
Control levelLow (prompt-driven)High (explicit)

​
Video Agent — best for speed

Send a text prompt, get a video. The agent handles scripting, avatar selection, and scene composition automatically. 
curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 60-second onboarding video for our SaaS product. Friendly tone.",
    "callback_url": "https://yourapp.com/webhook/heygen"
  }'
Use when:
  • You want a video fast without managing avatars or scripts
  • You’re building a product where end users describe videos in natural language
  • You want to iterate interactively — use mode: "chat" to review the storyboard before rendering
Trade-off: Less control over exact scene composition and creative choices.

​
Direct Video — best for control

Explicitly specify the avatar, voice, and script. Predictable, repeatable output for automated pipelines. 
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "your_look_id",
    "voice_id": "your_voice_id",
    "script": "Hi there! This video was created just for you.",
    "callback_url": "https://yourapp.com/webhook/heygen"
  }'
Use when:
  • Building automated pipelines (personalized sales videos, daily reports)
  • You need exact control over avatar, voice, and script
  • Generating videos programmatically from data (CRM records, form submissions)
Trade-off: You handle all creative decisions — avatar IDs and voice IDs must be known upfront.

​
Not sure which to pick?

Start with Video Agent. If you need precise control over the script, avatar, or timing, switch to POST /v3/videos. You can also combine both — use Video Agent to explore ideas and find the right style, then recreate with explicit parameters for the final production version.