Skip to main content

Overview

Video batches let you submit many videos in one request instead of calling POST /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.
The lipsync, video translation and asset batches follow the same mechanics described on this page.

Create a Batch

  • Endpoint: POST /v3/videos/batches
  • Purpose: Queue 1 to 100 video creation payloads in videos and return a batch_id immediately.
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 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}
  • 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 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 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}.