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

<video autoPlay loop muted playsInline poster="/images/quick-start/hero.jpg">
  <source src="https://mintcdn.com/heygen-1fa696a7/rL-bxk8oSp0H1JWc/images/quick-start/hero.mp4?fit=max&auto=format&n=rL-bxk8oSp0H1JWc&q=85&s=22664d9ae369c78f2a242bf546d10790" type="video/mp4" />
</video>

## What you can build

### Start from your own media

Send a prompt, photo, recording or text straight to the latest HeyGen model. Nothing to set up in HeyGen first.

> [card] [Video](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md)
>
> HeyGen Video 1. Prompt or image to video with sound.

> [card] [Avatar](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md)
>
> HeyGen Avatar 6. Photo and voice to a talking video.

> [card] [Voice](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-voice.md)
>
> HeyGen Voice 1. Speech from text or a recording.

> [card] [Image](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-image.md)
>
> HeyGen Image 1. One identity, any scene.

### Build on what you set up in HeyGen

Reuse your avatars, voices, brand kits and templates, referenced by ID.

> [card] [Video](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md)
>
> Avatar video, Video Agent, Studio, Templates.

> [card] [Avatar and Voice](https://heygen-1fa696a7.mintlify.site/docs/create-avatar.md)
>
> Your avatars and voice clones.

> [card] [Brand](https://heygen-1fa696a7.mintlify.site/docs/brand-kits.md)
>
> Brand kits and glossaries.

> [card] [Realtime Video](https://heygen-1fa696a7.mintlify.site/live-avatar.md)
>
> Live, conversational avatars.

> [card] [Video Translation](https://heygen-1fa696a7.mintlify.site/docs/video-translate.md)
>
> 175+ languages with lip-sync.

> [card] [Lipsync](https://heygen-1fa696a7.mintlify.site/lipsync-speed.md)
>
> New audio on an existing video.

> [card] [Tools](https://heygen-1fa696a7.mintlify.site/background-music.md)
>
> Music, sound effects, clipping, cleanup.

> [card] [Batches](https://heygen-1fa696a7.mintlify.site/batch-videos.md)
>
> Up to 100 requests in one call.

## 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 what I already have, then pick the endpoint by input (the "Choose an endpoint" list in llms.txt):
   - A talking video from a photo of a person and a script or voice recording: HeyGen Avatar 6, POST /v3/models/avatars, poll GET /v3/models/videos/{video_id}. For a script, first generate the speech with POST /v3/models/audio/tts and pass its audio_url.
   - A video from a prompt or an image, including cartoon or mascot characters: HeyGen Video, POST /v3/models/videos, poll GET /v3/models/videos/{video_id}
   - Speech from text: HeyGen Voice, POST /v3/models/audio/tts
   - One person in a new scene: HeyGen Image, POST /v3/models/images with 1 to 5 identity photos and exactly one reference image
   - My own avatar, voice clone or template: POST /v3/videos, Video Agent or templates, referenced by ID
3. Make the first call, poll until it finishes, and give me the result URL.
```

## Your first video

> [card] [Get your API key](https://platform.heygen.com/api-keys)
>
> Create a key in the API dashboard. Every request below needs it.

> [card] [Try it in the Playground](https://heygen-1fa696a7.mintlify.site/reference/create-heygen-video.md)
>
> Fire a real request from your browser before writing any code.

> [!NOTE]
>
> **Base URL** `https://api.heygen.com` · **Auth header** `X-Api-Key: <your-key>`

**1. Authenticate**

Create a key in the [API keys page](https://platform.heygen.com/api-keys). For key rotation, see the [API Key guide](https://heygen-1fa696a7.mintlify.site/docs/api-key.md).

```bash theme={null}
export HEYGEN_API_KEY="your-api-key-here"
```

**2. Create a video**

Call a model directly. Pass public URLs for your photo and recording, or [upload](https://heygen-1fa696a7.mintlify.site/docs/upload-assets.md) them and pass an `asset_id`.

> [tab] HeyGen Avatar 6
>
> A photo and a voice recording become a talking video. See [HeyGen Avatar 6](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md).
>
> ```bash theme={null}
> curl -X POST "https://api.heygen.com/v3/models/avatars" \
>   -H "X-Api-Key: $HEYGEN_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "heygen-avatar-6",
>     "reference_images": [{ "type": "url", "url": "https://example.com/photo.jpg" }],
>     "audio": { "type": "url", "url": "https://example.com/speech.wav" }
>   }'
> ```

> [tab] HeyGen Video
>
> A prompt becomes a clip with its own sound. See [HeyGen Video](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md).
>
> ```bash theme={null}
> curl -X POST "https://api.heygen.com/v3/models/videos" \
>   -H "X-Api-Key: $HEYGEN_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "heygen-video-1",
>     "mode": "text_to_video",
>     "prompt": "A presenter in a bright studio smiles and says: welcome to our product launch.",
>     "duration": 5,
>     "aspect_ratio": "16:9"
>   }'
> ```

```json Response theme={null}
{ "data": { "video_id": "VIDEO_ID", "status": "pending" } }
```

**3. Get the result**

Both models return their video on [`GET /v3/models/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-heygen-video). Poll until `status` is `completed`, then download `video_url`.

> [tab] Python
>
> ```python theme={null}
> import os, time, requests
>
> HEADERS = {"X-Api-Key": os.environ["HEYGEN_API_KEY"]}
> video_id = "VIDEO_ID"  # from the create response
>
> while True:
>     video = requests.get(
>         f"https://api.heygen.com/v3/models/videos/{video_id}",
>         headers=HEADERS,
>     ).json()["data"]
>     if video["status"] in ("completed", "failed", "cancelled"):
>         break
>     time.sleep(10)
>
> print(video.get("video_url") or video.get("failure_message"))
> ```

> [tab] curl
>
> ```bash theme={null}
> curl "https://api.heygen.com/v3/models/videos/VIDEO_ID" \
>   -H "X-Api-Key: $HEYGEN_API_KEY"
> ```

```json Response (completed) theme={null}
{ "data": { "video_id": "VIDEO_ID", "status": "completed", "video_url": "https://resource2.heygen.ai/videos/.../VIDEO.mp4", "duration": 5 } }
```

> [!TIP]
>
> Ready to reuse your own avatar or voice? Create an avatar once, then render it by `avatar_id` with [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/generate-avatar-video).

## Working from an agent or terminal?

Skip the raw HTTP. Both surfaces wrap the same API.

> [card] [MCP Server](https://heygen-1fa696a7.mintlify.site/mcp/overview.md)
>
> Plug HeyGen into Claude, Cursor, or any MCP-capable agent. It handles the calls for you.

> [card] [CLI](https://heygen-1fa696a7.mintlify.site/cli.md)
>
> `heygen video create`, `heygen video download`. Scriptable from any shell or CI job.

## Build with your stack

> [card] [Webhooks](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md)

> [card] [Authentication](https://heygen-1fa696a7.mintlify.site/docs/api-key.md)

> [card] [Usage Limits](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md)

> [!NOTE]
>
> Still calling **v1/v2**? Those endpoints passed their October 31, 2026 sunset and are being removed. Calls to them may fail intermittently, so move to v3: see the [version comparison](https://heygen-1fa696a7.mintlify.site/endpoint-version-comparison.md).

## Troubleshooting

> [accordion] Video status is failed
>
> Inspect `failure_code` and `failure_message` on [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video). Full catalog in [Error Codes](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md).

> [accordion] 401 Unauthorized
>
> Confirm the `X-Api-Key` header is set and the key is active in the [API keys page](https://platform.heygen.com/api-keys).

> [accordion] 429 Too Many Requests
>
> Rate or concurrency limit hit. Respect `Retry-After` and back off. Enterprise plans get higher limits; see [Usage Limits](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md).

> [accordion] 400 download\_failed
>
> 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.