Skip to main content

Overview

Asset batches parallelize the direct upload flow: instead of presigning, uploading, and completing files one by one, you request up to 100 presigned upload slots in a single call, PUT all the files in parallel, and finalize the whole batch with one request.
  1. POST /v3/assets/direct-uploads/batches: get an asset_id + presigned upload_url per file.
  2. PUT each file’s raw bytes to its upload_url, sending upload_headers verbatim.
  3. POST /v3/assets/complete/batches: finalize, then poll GET /v3/assets/batches/{batch_id}.
A batch holds up to 100 files. No file bytes flow through the HeyGen API: uploads go straight to S3. On completion, each file is validated and ingested independently, so one bad file does not fail the rest.

Step 1: Create a Batch of Upload Slots

POST /v3/assets/direct-uploads/batches presigns 1 to 100 direct-to-S3 upload slots and returns them synchronously with a batch_id, in the submitted order, one per file.
Each entry in files has the same shape as a single direct upload (filename, content_type, exact size_bytes, optional checksum_sha256), and each slot comes back with the same fields: asset_id, upload_url, upload_headers, expires_in_seconds, max_bytes and status pending_upload. The batch-level callback_url is reserved for parity with the other batch APIs; track completion by polling the batch. Per-file size limits match direct upload: up to 200 MB (209,715,200 bytes), 1.5 GB for audio, or 1 GiB for a HyperFrames project zip. A larger size_bytes fails the whole request with Invalid file(s) at index N: File too large. Pass an Idempotency-Key header to make retries safe: replaying the same key returns the same batch and the same slots.

Step 2: Upload the Files

PUT each file’s raw bytes to its upload_url, sending the returned upload_headers verbatim. Uploads are plain S3 PUTs, so you can run them in parallel from any HTTP client, following the same S3 rules as a single upload:
Each upload_url expires after expires_in_seconds: request a fresh batch if a slot lapses before you upload.

Step 3: Complete and Poll

Once every PUT has returned 200, call POST /v3/assets/complete/batches once:
The call returns 202 Accepted: validation and ingestion run asynchronously per file. The call is idempotent: repeating it re-drives the same batch. Poll GET /v3/assets/batches/{batch_id} for per-item progress. The response shape matches the video batch.
The batch read model is shared across the batch APIs, so the per-item id field is named video_id. For asset batches it holds the asset id. Once an item is completed, that asset id is usable anywhere assets are accepted, e.g. as audio_asset_id in video creation or as an asset_id source in translation and lipsync batches.

Bulk Statuses

GET /v3/assets/statuses checks up to 100 assets in one request, across batches or for assets uploaded individually. Pass comma-separated asset_ids, or batch_ids (each expands to its member assets). Statuses are queued, processing, completed, or failed, plus not_found for unknown or unowned ids.