> ## 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.
# Quick Start
> Generate your first AI video with the HeyGen API in minutes — authenticate, send one request, and get back an MP4.
Create a key in Settings → API. Every request below needs it.
Fire a real request from your browser — before writing any code.
**Base URL** `https://api.heygen.com` · **Auth header** `X-Api-Key: `
## Your first video
Create a key in [Settings → API](https://app.heygen.com/home?from=\&nav=API). For OAuth and rotation, see the [API Key guide](/docs/api-key).
```bash theme={null}
export HEYGEN_API_KEY="your-api-key-here"
```
Send a prompt to the [Video Agent](/reference/create-video-agent-session) — it scripts, picks the avatar and voice, and renders.
```bash theme={null}
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 presenter explaining our product launch in 30 seconds"}'
```
```python theme={null}
import requests
resp = requests.post(
"https://api.heygen.com/v3/video-agents",
headers={"X-Api-Key": HEYGEN_API_KEY},
json={"prompt": "A presenter explaining our product launch in 30 seconds"},
)
session_id = resp.json()["data"]["session_id"]
```
```javascript theme={null}
const resp = await fetch("https://api.heygen.com/v3/video-agents", {
method: "POST",
headers: {
"X-Api-Key": process.env.HEYGEN_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "A presenter explaining our product launch in 30 seconds",
}),
});
const { session_id } = (await resp.json()).data;
```
```json Response theme={null}
{ "data": { "session_id": "sess_abc123", "status": "generating", "video_id": null } }
```
Watch it build live at `https://app.heygen.com/video-agent/{session_id}`.
Poll the session for a `video_id`, then the video for its `video_url` — or skip polling with a [webhook](/docs/webhooks) via `callback_url`.
```python theme={null}
import time
# 1. Wait for the video_id to be assigned
video_id = None
while not video_id:
sess = requests.get(
f"https://api.heygen.com/v3/video-agents/{session_id}",
headers={"X-Api-Key": HEYGEN_API_KEY},
).json()["data"]
video_id = sess.get("video_id")
if not video_id:
time.sleep(5)
# 2. Poll the video until it's done
while True:
video = requests.get(
f"https://api.heygen.com/v3/videos/{video_id}",
headers={"X-Api-Key": HEYGEN_API_KEY},
).json()["data"]
if video["status"] in ("completed", "failed"):
break
time.sleep(10)
print(video["video_url"])
```
```bash theme={null}
# 1. Session → video_id
curl "https://api.heygen.com/v3/video-agents/sess_abc123" \
-H "X-Api-Key: $HEYGEN_API_KEY"
# 2. video_id → video_url
curl "https://api.heygen.com/v3/videos/vid_xyz789" \
-H "X-Api-Key: $HEYGEN_API_KEY"
```
```json Response (completed) theme={null}
{ "data": { "id": "vid_xyz789", "status": "completed", "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4", "duration": 32.5 } }
```
## Pick your endpoint
Prompt → finished video. **Flagship.**
Pick the avatar, voice, and script yourself.
Prompt-driven cinematic shots from avatar looks.
30+ languages with voice cloning and lip-sync.
Text → natural speech audio.
HTML/CSS/JS → motion-graphics video. **New.**
## Working from an agent or terminal?
Skip the raw HTTP — both surfaces wrap the same API.
Plug HeyGen into Claude, Cursor, or any MCP-capable agent — it handles the calls for you.
`heygen video create`, `heygen video download` — scriptable from any shell or CI job.
## Build with your stack
Migrating from **v1/v2**? Supported until **October 31, 2026** — see the [version comparison](/endpoint-version-comparison).
## Troubleshooting
Inspect `failure_code` and `failure_message` on [`GET /v3/videos/{video_id}`](/reference/get-video). Full catalog in [Error Codes](/docs/error-codes).
Confirm the `X-Api-Key` header is set and the key is active in [Settings → API](https://app.heygen.com/home?from=\&nav=API).
Rate or concurrency limit hit. Respect `Retry-After` and back off. See [Usage Limits](/docs/usage-limits).
A URL you passed couldn't be fetched — it must be publicly accessible and point directly at the file.