Choosing the Right Video API

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

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 '{\n    "prompt": "A 60-second onboarding video for our SaaS product. Friendly tone.",\n    "callback_url": "https://yourapp.com/webhook/heygen"\n  }'

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 '{\n    "type": "avatar",\n    "avatar_id": "your_look_id",\n    "voice_id": "your_voice_id",\n    "script": "Hi there! This video was created just for you.",\n    "callback_url": "https://yourapp.com/webhook/heygen"\n  }'

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.