HeyGen batch videos API: 100 videos in one call

HeyGen's batch endpoint, POST /v3/videos/batches, takes 1 to 100 ordinary video payloads in a videos array, answers 202 Accepted with a batch_id, and renders each item on its own. You poll that one id, or set a callback_url, instead of tracking 100 separate video ids yourself.

HeyGen's fields are from its batch page, read 2026-09-29. Sume's side is from the Bulk runs and Generation admission docs.

What can go in a HeyGen batch?

Each item has the exact shape POST /v3/videos accepts, discriminated by type, so anything you can create alone can be batched.

How do I submit and track a batch?

Send videos, plus an optional title and callback_url. The callback fires once, when every item has reached a terminal state. Otherwise poll GET /v3/videos/batches/{batch_id} and read counts_by_status. Items report queued, processing, completed or failed, and each one shows its video_id as soon as its video exists, so you can download finished videos while the rest render. Page through items with limit (1 to 100) and next_token.

curl -X POST "https://api.heygen.com/v3/videos/batches" \
  -H "x-api-key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Regional cuts",
    "videos": [
      { "type": "avatar", "avatar_id": "YOUR_LOOK_ID",
        "script": "Hello from North America!", "voice_id": "YOUR_VOICE_ID" },
      { "type": "avatar", "avatar_id": "YOUR_LOOK_ID",
        "script": "Hello from EMEA!", "voice_id": "YOUR_VOICE_ID" }
    ]
  }'

How do I read the batch status and failures?

The batch status is derived from its items and is one of processing, completed or failed. Per item, item_index is the zero-based position in the array you submitted, so you can match results back to your own list. A failed item carries an error object, and has_more tells you whether another page of items exists. HeyGen's page carries no price, so this post does not quote one; see HeyGen API pricing for how its credits work.

Are batch retries safe?

Pass an Idempotency-Key header. Replaying the same key returns the original batch rather than creating a duplicate, and if the first request is still being processed the API answers 409.

What does Sume offer instead of a batch endpoint?

For avatar videos, the Sume docs checked describe one job per request: submit each with an Idempotency-Key and mode: "async", poll each job's status, and watch the generation_limits returned by submit responses so you stop adding work when queue capacity is low. A server-side queue does exist for Formats: bulk runs queue up to 100 Format runs with a concurrency window and are polled at GET /v1/format-run-queues/{id}. Those are Format runs, not talking-avatar requests, so check that a Format fits your job before you use it. For the bulk pattern in practice, see Format bulk runs.