# 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 | 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
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
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.