Choosing the Right Video API

Compare Video Agent and direct video creation to pick the right approach for your use case.

HeyGen offers two ways to create videos programmatically. The right choice depends on how much control you need.

	Video Agent	Direct Video
Endpoint	POST /v3/video-agents	POST /v3/videos
Input	Natural language prompt	Structured JSON
Script writing	Agent writes it	You write it
Avatar selection	Agent picks (or you override)	You specify
Voice selection	Agent picks (or you override)	You specify
Interactive iteration	✅ Via chat mode	❌
Webhook support	✅ callback_url	✅ callback_url
Control level	Low (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.