Skip to main content
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.