HEheygen
Batches

Create Video Batch

Changed on

Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll GET /v3/videos/batches/{batch_id} for per-item video ids and statuses.

post/v3/videos/batches

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/videos/batches
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

Idempotency-Keystring

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Request body

titlestring nullable

Display name for the batch, shown in the HeyGen app.

folder_idstring nullable

Destination folder ID for the batch container. The videos remain grouped inside the newly created batch; the batch itself is placed in this folder. Omit, pass null, or pass an empty string to place the batch at the workspace root.

callback_urlstring nullable

Webhook URL invoked once when every item in the batch reaches a terminal state.

Response

Accepted — submission acknowledged; poll for completion.

Changes

  • 7dfa5e59b4f5Revision changes
    • breaking

      removed from the / request property oneOf list

    • info

      added the new optional request property

    • info

      added avatar cinematic_avatar image studio discriminator mapping keys to the / request property

    • info

      added to the / request property oneOf list

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status