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

# Usage Limits

> See HeyGen API rate limits by endpoint and plan tier. Includes concurrent video render quotas, request-per-minute caps, and how to request a quota increase.

## Concurrency Limits

| Plan          | Max Concurrent Video Jobs |
| :------------ | :------------------------ |
| Pay-As-You-Go | 10                        |

Concurrent jobs include any asynchronous generation in progress: [Video Agent sessions](/docs/video-agent), avatar video renders, and [video translations](/docs/video-translate). Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header — see the [`rate_limit_exceeded` error](/docs/error-codes#rate-limit-exceeded).

## Endpoint Limits

### Video Generation Input

Resources provided to [`POST /v3/videos`](/reference/create-video) must meet these limits. Invalid resources will cause render failures with [`download_failed`](/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` (from [`POST /v3/assets`](/reference/upload-asset)), an HTTPS URL, or base64-encoded content. See [Upload Assets](/docs/upload-assets).

### Asset Upload ([`POST /v3/assets`](/reference/upload-asset))

* **Maximum file size:** 32 MB. The same limit applies to files provided by URL. For larger files, use the [direct upload flow](/docs/upload-assets#upload-large-files-direct-upload) ([`POST /v3/assets/direct-uploads`](/reference/create-asset-upload)) — its per-upload cap is returned as `max_bytes` in the initialize response.
* **Supported types:** Image (PNG, JPEG), video (MP4, WebM), audio (MP3, WAV), and PDF.

### Text-to-Speech Input ([`POST /v3/voices/speech`](/reference/generate-speech))

* **Text length:** 1–5,000 characters.
* **Speed multiplier:** 0.5× to 2.0×.
* **Input type:** Plain text or SSML markup.

### Output Video Specifications

* **Frame rate:** 25 fps for videos containing avatars.
* **Resolution:** Width and height must each be between 128 and 4,096 pixels. Default output is 1080p.
* **Aspect ratio:** 16:9 or 9:16.
* **Maximum scenes:** 50 per video.
* **Maximum duration:** 30 minutes.

## 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`](/reference/list-videos)                          | 10      | 100 |
| [`GET /v3/avatars`](/reference/list-avatar-groups)                  | 20      | 50  |
| [`GET /v3/avatars/looks`](/reference/list-avatar-looks)             | 20      | 50  |
| [`GET /v3/voices`](/reference/list-voices)                          | 20      | 100 |
| [`GET /v3/video-agents/styles`](/reference/list-video-agent-styles) | 20      | 100 |
| [`GET /v3/video-translations`](/reference/list-video-translations)  | 10      | 100 |
| [`GET /v3/webhooks/endpoints`](/reference/list-webhook-endpoints)   | 10      | 100 |
| [`GET /v3/webhooks/events`](/reference/list-webhook-events)         | 10      | 100 |
| `GET /v3/video-agents/sessions/{id}/resources`                      | 8       | 100 |

## Rate Limiting

All endpoints enforce rate limits. When exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header indicating the number of seconds to wait before retrying. See [`rate_limit_exceeded`](/docs/error-codes#rate-limit-exceeded) for the error shape and recommended backoff strategy.