> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Asset Uploads

> Upload up to 100 files in one batch: request presigned S3 slots in a single call, PUT the bytes in parallel, then finalize and poll one batch id.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-4.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=ed7eea7e860c769f9b1b12804a27315a)

## Overview

Asset batches parallelize the [direct upload flow](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md): 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`](https://heygen-1fa696a7.mintlify.site/reference/create-asset-upload-batch): 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`](https://heygen-1fa696a7.mintlify.site/reference/complete-asset-upload-batch): finalize, then poll [`GET /v3/assets/batches/{batch_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-asset-batch).

> [!NOTE]
>
> 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`](https://heygen-1fa696a7.mintlify.site/reference/create-asset-upload-batch) presigns 1 to 100 direct-to-S3 upload slots and returns them synchronously with a `batch_id`, **in the submitted order**, one per file.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/assets/direct-uploads/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Webinar recordings, October",
    "files": [
      { "filename": "session-1.mp4", "content_type": "video/mp4", "size_bytes": 157286400 },
      { "filename": "session-2.mp4", "content_type": "video/mp4", "size_bytes": 183500800 }
    ]
  }'
```

Each entry in `files` has the same shape as a [single direct upload](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md#step-1-create-the-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](#step-3-complete-and-poll).

Per-file [size limits](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md#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](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md#step-2-put-the-bytes-to-s3) as a single upload:

```bash theme={null}
curl -X PUT "https://heygen-uploads.s3.amazonaws.com/..." \
  -H "Content-Type: video/mp4" \
  --data-binary @session-1.mp4
```

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`](https://heygen-1fa696a7.mintlify.site/reference/complete-asset-upload-batch) once:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/assets/complete/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "batch_id": "batch_as_abc123" }'
```

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}`](https://heygen-1fa696a7.mintlify.site/reference/get-asset-batch) for per-item progress. The response shape matches the [video batch](https://heygen-1fa696a7.mintlify.site/batch-videos.md#response-fields).

> [!NOTE]
>
> 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](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md) or as an `asset_id` source in [translation](https://heygen-1fa696a7.mintlify.site/batch-video-translations.md) and [lipsync](https://heygen-1fa696a7.mintlify.site/batch-lipsyncs.md) batches.

## Bulk Statuses

[`GET /v3/assets/statuses`](https://heygen-1fa696a7.mintlify.site/reference/bulk-asset-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.