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

# Usage Limits

> See HeyGen API rate limits by endpoint and plan tier. Includes concurrent video render quotas, burst concurrency for Enterprise, request-per-minute caps, and input limits.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-7.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=02bcf90d74d8b9887ce224de6b8a130b)

## Concurrency Limits

| Plan | Included Concurrent Workflows | Burst |
| :- | :- | :- |
| Pay-As-You-Go | 10 | — |
| Enterprise | 20 | Up to +50 per workflow type at 1.5× |

Concurrent jobs include any asynchronous generation in progress: [Video Agent sessions](https://heygen-1fa696a7.mintlify.site/docs/video-agent.md), avatar video renders, and [video translations](https://heygen-1fa696a7.mintlify.site/docs/video-translate.md). Burst applies to avatar video renders and video translations, each with its own pool of extra slots. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header — see the [`rate_limit_exceeded` error](https://heygen-1fa696a7.mintlify.site/docs/error-codes#rate-limit-exceeded).

### Burst

Enterprise workspaces can opt in to [burst concurrency](https://heygen-1fa696a7.mintlify.site/docs/burst.md): up to 50 extra workflows per type on demand, with only the workflows above the included slots billed at **1.5×** the contract rate.

## Endpoint Limits

### Video Generation Input

Resources provided to [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) must meet these limits. Invalid resources will cause render failures with [`download_failed`](https://heygen-1fa696a7.mintlify.site/docs/error-codes#download-failed).

| Resource Type | Supported Formats | Max File Size | Max Resolution |
| :- | :- | :- | :- |
| Video | MP4, WebM | 100 MB | \< 2K |
| Image | JPG, PNG | 50 MB | \< 2K |
| Audio | WAV, MP3 | 50 MB | — |

Requirements:

* Resource URLs must be **publicly accessible** (no authentication required).
* The file extension must **match the actual file format**.
* Files must not be **corrupted or malformed**.

### Avatar Input

* **Script text:** Maximum 5,000 characters.
* **Audio input:** Maximum 10 minutes (600 seconds).

### Video Agent Input

* **Prompt:** 1–10,000 characters.
* **File attachments:** Up to 20 files. Supported types: image (PNG, JPEG), video (MP4, WebM), audio (MP3, WAV), and PDF.
* Files can be provided as an `asset_id`, an HTTPS URL, or base64-encoded content. See [Assets](https://heygen-1fa696a7.mintlify.site/assets.md#pass-a-file-to-an-endpoint).

### Asset Upload

Per-method size limits and supported types for [`POST /v3/assets`](https://heygen-1fa696a7.mintlify.site/reference/upload-asset), [direct upload](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md) (cap returned as `max_bytes`) and inputs passed by URL or base64 are on the [Assets overview](https://heygen-1fa696a7.mintlify.site/assets.md#choose-an-upload-method).

### Output Video Specifications

* **Frame rate:** 25 fps for videos containing avatars.
* **Resolution:** Width and height must each be between 128 and 4,096 pixels. Defaults to 720p for `avatar`, `image` and `cinematic_avatar` videos, and 1080p for `studio` videos.
* **Aspect ratio:** `16:9` (default), `9:16`, `4:5`, `5:4`, `1:1` or `auto` for `avatar`, `image` and `studio` videos. `cinematic_avatar` takes `16:9`, `9:16` or `1:1`.
* **Maximum scenes:** 50 per video.
* **Maximum duration:** 30 minutes per scene.

> [!NOTE]
>
> The cap is per scene. An `avatar` or `image` request to [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) renders a single scene, so 30 minutes is also its whole-video maximum. The multi-scene modes — [studio videos](https://heygen-1fa696a7.mintlify.site/studio-videos.md) and [templates](https://heygen-1fa696a7.mintlify.site/templates.md) — run as long as the sum of their scenes, provided each scene stays within 30 minutes. A scene over the cap fails during rendering.

## Pagination

Most list endpoints use cursor-based pagination with a `limit` parameter and `next_token` for the next page.

| Endpoint | Default | Max |
| :- | :- | :- |
| [`GET /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/list-videos) | 10 | 100 |
| [`GET /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-groups) | 20 | 50 |
| [`GET /v3/avatars/looks`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-looks) | 20 | 50 |
| [`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices) | 10 | 100 |
| [`GET /v3/video-agents/styles`](https://heygen-1fa696a7.mintlify.site/reference/list-video-agent-styles) | 20 | 100 |
| [`GET /v3/video-translations`](https://heygen-1fa696a7.mintlify.site/reference/list-video-translations) | 10 | 100 |
| [`GET /v3/webhooks/endpoints`](https://heygen-1fa696a7.mintlify.site/reference/list-webhook-endpoints) | 10 | 100 |
| [`GET /v3/webhooks/events`](https://heygen-1fa696a7.mintlify.site/reference/list-webhook-events) | 10 | 100 |

## Rate Limiting

Request-rate limits apply per user and per endpoint path, and depend on your plan and the type of endpoint. Requests to a path that contains an ID, such as [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video), are counted separately for each ID.

| Endpoint type | Examples | Pay-As-You-Go and subscription | Enterprise |
| :- | :- | :- | :- |
| Read | [`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices), [`GET /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/list-videos) | 300 per minute | 1,000 per minute |
| Write | [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) | 10 per second | 30 per second |
| Heavy | [`POST /v3/assets`](https://heygen-1fa696a7.mintlify.site/reference/upload-asset) | 30 per minute | 120 per minute |
| Status polling | [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) and the other status endpoints | 500 per minute, and 600 per minute per IP address | 1,500 per minute, and 1,800 per minute per IP address |

The Enterprise column applies to workspaces on an Enterprise API plan. Enterprise workspaces can also ask their account team for custom limits on specific endpoints.

### Endpoints with fixed limits

These endpoints have the same limit on every plan:

| Endpoint | Limit |
| :- | :- |
| [`POST /v3/videos/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-batch) | 30 per minute |
| [`POST /v3/video-translations/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation-batch) | 30 per minute |
| [`POST /v3/lipsyncs/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync-batch) | 30 per minute |
| [`POST /v3/assets/direct-uploads/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-asset-upload-batch) | 30 per minute |
| [`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/reference/create-hyperframes-render) | 5 per second |
| [`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech) | 30 per minute |
| [Speech WebSockets](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md#socket-limits) | 30 per minute, shared with Stream Speech. Each handshake, token request, and new `multi-stream-input` context counts. |
| [`POST /v3/models/audio/sts`](https://heygen-1fa696a7.mintlify.site/docs/voices/speech-to-speech) | 30 per minute |
| [`POST /v3/models/decisions`](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-decision) | 100 per second, shared by the API keys of one user in one workspace |

### When you exceed a limit

The API returns `429 Too Many Requests` with the [`rate_limit_exceeded`](https://heygen-1fa696a7.mintlify.site/docs/error-codes#rate-limit-exceeded) error. The error message names the limit you hit, and the response includes these headers:

| Header | Meaning |
| :- | :- |
| `Retry-After` | Seconds to wait before retrying. |
| `X-RateLimit-Limit` | Requests allowed in the window you exceeded. |
| `X-RateLimit-Remaining` | Requests left in that window. |
| `X-RateLimit-Reset` | When the window resets, in Unix epoch seconds. |
| `X-RateLimit-Scope` | `user` or `ip`: whether you hit the per-user or the per-IP limit. |

The text-to-speech model endpoints return `Retry-After` only. Wait at least `Retry-After` seconds, then retry with exponential backoff.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.