> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/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.
## What you can build
A digital twin from video, or an avatar from one photo.
Prompt to finished video. Edit single scenes after.
Text, image, or reference to a 5โ15s clip, up to 2K. **New.**
Your avatar, voice, and script, up to Avatar V.
Your identity, a new look. Portraits from reference photos.
Turn any video into a template, then one call per viewer. **New.**
Dress an avatar in a curated set of looks.
HTML, CSS, and JS to motion-graphics video.
One recording to a HeyGen Voice in seconds. **New.**
Studio-grade voice trained on 20+ minutes of audio.
Completed or streaming speech from your HeyGen Voice. **New.**
175+ languages with voice cloning and lip-sync.
## Start with your agent
Paste this into [Claude Code](https://claude.com/claude-code), [Codex](https://openai.com/codex/), or Cursor. It reads the whole API, sets up your key, and makes your first video with you.
```text Prompt for your agent wrap theme={null}
I want to build with the HeyGen API. Run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.
Read these first and follow them exactly:
- https://developers.heygen.com/llms.txt (index of every guide and endpoint)
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)
Then:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me.
2. Ask me what I want to make, and pick the right endpoint from the docs (Video Agent, HeyGen Video, avatar video, HeyGen Image, templates, voice cloning, text to speech, or translation).
3. Make the first call, poll until it finishes, and give me the result URL.
```
## Your first video
Create a key in the API dashboard. 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: `
Create a key in the [API keys page](https://platform.heygen.com/api-keys). For key 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 } }
```
## 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 the [API keys page](https://platform.heygen.com/api-keys).
Rate or concurrency limit hit. Respect `Retry-After` and back off. Enterprise plans get higher limits; 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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.