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

# Videos

> Submit up to 100 video creation requests in a single call. Queue avatar, image, and cinematic avatar videos together, then poll one batch id for per-item progress.

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

## Overview

Video batches let you submit many videos in one request instead of calling [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) once per video. You send an array of video payloads, get back a single `batch_id` right away, and poll that one id for the status and `video_id` of every item.

Each item in a batch is a standard video creation payload, the exact shape [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) accepts, so any [Digital Twin](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md) (`type: "avatar"`), [image](https://heygen-1fa696a7.mintlify.site/image-to-video.md) (`image`), or [Cinematic Avatar](https://heygen-1fa696a7.mintlify.site/cinematic-avatar.md) (`cinematic_avatar`) video you can create on its own can be batched.

> [!NOTE]
>
> A batch holds up to **100** items. Submission is asynchronous: the response acknowledges the batch, and each video renders on its own. Poll the batch to collect video ids as they become available.

The [lipsync](https://heygen-1fa696a7.mintlify.site/batch-lipsyncs.md), [video translation](https://heygen-1fa696a7.mintlify.site/batch-video-translations.md) and [asset](https://heygen-1fa696a7.mintlify.site/batch-assets.md) batches follow the same mechanics described on this page.

## Create a Batch

* Endpoint: [`POST /v3/videos/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-batch)
* Purpose: Queue 1 to 100 video creation payloads in `videos` and return a `batch_id` immediately.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "October product update, regional cuts",
    "callback_url": "https://example.com/hooks/heygen",
    "videos": [
      {
        "type": "avatar",
        "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
        "script": "Hello from the North America team!",
        "voice_id": "YOUR_VOICE_ID"
      },
      {
        "type": "avatar",
        "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
        "script": "Hello from the EMEA team!",
        "voice_id": "YOUR_VOICE_ID"
      }
    ]
  }'
```

The call returns `202 Accepted` with a `batch_id`: the batch is queued, not finished. The optional `title` names the batch in the HeyGen app, and `callback_url` is a [webhook](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md) invoked once, when every item reaches a terminal state.

### Idempotency

Pass an `Idempotency-Key` header to make retries safe: replaying the same key returns the original batch instead of creating a duplicate. If a request with that key is still being processed, the API responds with `409`.

## Get a Batch

* Endpoint: [`GET /v3/videos/batches/{batch_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-batch)
* Purpose: Return the batch's aggregate status plus one page of items (`limit` 1–100, default `100`; `token` from the previous `next_token`).

### Response Fields

The batch carries an aggregate `status` derived from item states (`processing`, `completed` or `failed`), `total_items`, `counts_by_status` (item counts keyed by item status), and a page of `items` ordered by `item_index`, the zero-based position in the submitted array. Each item has a `status` (`queued`, `processing`, `completed` or `failed`), a `video_id` once the underlying video has been created, and `error` details when it failed. The [reference](https://heygen-1fa696a7.mintlify.site/reference/get-video-batch.md) has the full schema.

## Tracking completion

You have two ways to know when work finishes, and they pair well:

* **Webhook (push).** Set `callback_url` on the batch to be notified once, when the last item reaches a terminal state. See [Webhooks](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md) to register an endpoint and verify signatures.
* **Polling (pull).** Call `GET /v3/videos/batches/{batch_id}` and read `counts_by_status`. Individual items surface a `video_id` the moment their video is created, so you can start downloading finished videos while the rest of the batch is still rendering.

For large batches, page through `items` with `limit` and `next_token` until `has_more` is `false`, then fetch each finished video with [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video).


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