Overview
Video batches let you submit many videos in one request instead of callingPOST /v3/videos 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 accepts, so any Digital Twin (type: "avatar"), image (image), or Cinematic Avatar (cinematic_avatar) video you can create on its own can be batched.
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.
Create a Batch
- Endpoint:
POST /v3/videos/batches - Purpose: Queue 1 to 100 video creation payloads in
videosand return abatch_idimmediately.
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 invoked once, when every item reaches a terminal state.
Idempotency
Pass anIdempotency-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} - Purpose: Return the batch’s aggregate status plus one page of items (
limit1–100, default100;tokenfrom the previousnext_token).
Response Fields
The batch carries an aggregatestatus 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 has the full schema.
Tracking completion
You have two ways to know when work finishes, and they pair well:- Webhook (push). Set
callback_urlon the batch to be notified once, when the last item reaches a terminal state. See Webhooks to register an endpoint and verify signatures. - Polling (pull). Call
GET /v3/videos/batches/{batch_id}and readcounts_by_status. Individual items surface avideo_idthe moment their video is created, so you can start downloading finished videos while the rest of the batch is still rendering.
items with limit and next_token until has_more is false, then fetch each finished video with GET /v3/videos/{video_id}.
