> ## 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.

# Direct Upload to S3

> Upload large files straight to S3 with a presigned URL: up to 200 MB per video, image, or PDF, 1.5 GB per audio file, and 1 GiB per HyperFrames zip. Three calls: create the upload, PUT the bytes, complete.

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

Direct upload sends file bytes from your client straight to S3 through a presigned URL, so they never pass through the HeyGen API. Use it for any file over the [simple upload](https://heygen-1fa696a7.mintlify.site/docs/upload-assets.md) limit, for avatar training footage, and for HyperFrames project zips. The result is an ordinary `asset_id` you can pass to any endpoint that accepts [assets](https://heygen-1fa696a7.mintlify.site/assets.md).

**1. Create the upload**

[`POST /v3/assets/direct-uploads`](https://heygen-1fa696a7.mintlify.site/reference/create-asset-upload) with the file's name, MIME type, and exact byte size. Returns an `asset_id`, a presigned `upload_url`, and `upload_headers`.

**2. PUT the bytes to S3**

`PUT` the raw file to `upload_url` with every header from `upload_headers`, within 24 hours.

**3. Complete the upload**

[`POST /v3/assets/{asset_id}/complete`](https://heygen-1fa696a7.mintlify.site/reference/complete-asset-upload). The `asset_id` is usable as soon as this returns.

To upload many files at once, use the [batch variant](https://heygen-1fa696a7.mintlify.site/batch-assets.md): up to 100 upload slots in one call and one complete call for the whole batch.

## Size limits

| File type | `content_type` | Max size |
| - | - | - |
| Video | `video/mp4`, `video/webm`, `video/quicktime` (.mov) | 200 MB (209,715,200 bytes) |
| Image | `image/png`, `image/jpeg`, `image/webp`, `image/heic`, `image/heif` | 200 MB (209,715,200 bytes) |
| Document | `application/pdf` | 200 MB (209,715,200 bytes) |
| Subtitles | `application/x-subrip` (.srt) | 200 MB (209,715,200 bytes) |
| Audio | `audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/x-wav`, `audio/webm` | 1.5 GB (1,500,000,000 bytes) |
| HyperFrames project | `application/zip` | 1 GiB (1,073,741,824 bytes) |

The limit for your file is also returned as `max_bytes` when you create the upload. A larger `size_bytes` is rejected at that step, before any bytes move.

## Step 1: Create the upload

```bash theme={null}
INIT=$(curl -s -X POST "https://api.heygen.com/v3/assets/direct-uploads" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "training-footage.mp4",
    "content_type": "video/mp4",
    "size_bytes": 157286400
  }')
ASSET_ID=$(echo "$INIT" | jq -r '.data.asset_id')
UPLOAD_URL=$(echo "$INIT" | jq -r '.data.upload_url')
```

The [reference](https://heygen-1fa696a7.mintlify.site/reference/create-asset-upload.md) has the full request and response schema. What to watch:

* `filename` is kept as the asset name; the stored file's extension comes from `content_type`.
* `content_type` must come from the [size limits](#size-limits) table. SVG is rejected. It is checked against the stored bytes when you complete the upload.
* `size_bytes` must be the exact size, greater than 0. It is signed into `upload_url`, so the `PUT` must send exactly this many bytes.
* `checksum_sha256` (optional, 64 hex characters) makes S3 reject a `PUT` whose bytes do not match. See [Verify file integrity](#verify-file-integrity).

The response returns the `asset_id` (usable after [Step 3](#step-3-complete-the-upload)), `upload_url`, `upload_headers`, `expires_in_seconds` (86,400, or 24 hours), `max_bytes` for this `content_type`, and `status` `pending_upload`. Send an [`Idempotency-Key`](https://heygen-1fa696a7.mintlify.site/reference/create-asset-upload) header to retry this call safely: a repeat within 24 hours returns the same `asset_id` and `upload_url`.

## Step 2: PUT the bytes to S3

Send the file with every header from `upload_headers` (here, typically `content-type` and `x-amz-server-side-encryption`):

```bash theme={null}
HEADERS=()
while IFS= read -r h; do HEADERS+=(-H "$h"); done \
  < <(echo "$INIT" | jq -r '.data.upload_headers | to_entries[] | "\(.key): \(.value)"')
curl -sf -X PUT "$UPLOAD_URL" "${HEADERS[@]}" --upload-file ./training-footage.mp4
```

S3 returns `200` with an empty body when the upload succeeds. The request goes to S3, not to HeyGen, so it follows S3's rules:

* **Send every header in `upload_headers`, with its exact value.** They are part of the URL's signature. Read them from the response rather than hard-coding them, because the set changes with your request (a `checksum_sha256` adds `x-amz-checksum-sha256`).
* **Send exactly `size_bytes` bytes** in a single `PUT`. Chunked or multipart uploads are not supported on this URL.
* **Do not add your HeyGen API key** or any other header. Extra signed-looking headers can break the signature.
* **Finish within `expires_in_seconds`.** After 24 hours, create a new upload.

If the `PUT` fails, S3 returns an XML error. `SignatureDoesNotMatch` (403) means a header is missing or changed, or the body size differs from `size_bytes`. A failed `PUT` can be retried against the same `upload_url` until it expires.

## Step 3: Complete the upload

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/assets/$ASSET_ID/complete" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

The request body is required. Send `{}`, or `{"checksum_sha256": "<hex>"}` to cross-check the stored bytes.

The response returns the ready-to-use `asset_id`, the stored file's public `url`, the `mime_type` detected from the stored bytes, `size_bytes`, and `status` `processing`. Pass the `asset_id` to your next request right away; you do not need to wait for the status to change.

Complete is idempotent: calling it again returns the same asset. HeyGen reads the stored bytes at this step, so a file whose contents do not match a supported type is rejected here even if the `PUT` succeeded.

## Verify file integrity

Pass the file's SHA-256 as hex when you create the upload. HeyGen adds an `x-amz-checksum-sha256` header to `upload_headers`, and S3 rejects any `PUT` whose bytes do not match.

```bash theme={null}
SIZE=$(stat -f%z ./training-footage.mp4)  # use `stat -c%s` on Linux
SHA=$(shasum -a 256 ./training-footage.mp4 | cut -d' ' -f1)

curl -X POST "https://api.heygen.com/v3/assets/direct-uploads" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"training-footage.mp4\", \"content_type\": \"video/mp4\", \"size_bytes\": $SIZE, \"checksum_sha256\": \"$SHA\"}"
```

Send the returned `upload_headers` on the `PUT` as usual. You can pass the same hex value to the complete call as a final check.

## Upload a HyperFrames project

Zip the project and upload it with `content_type: "application/zip"` (up to 1 GiB). Pass the `asset_id` as the `project` of [`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/hyperframes). Reuse the same `asset_id` for every render of that project.

## Errors

| Step | Status | Error | Fix |
| - | - | - | - |
| Create | `400` | `invalid_parameter` | `content_type` is outside the [size limits](#size-limits) table or is SVG, `size_bytes` is 0 or over `max_bytes`, or `checksum_sha256` is not 64 hex characters. |
| PUT | `403` | `SignatureDoesNotMatch` (S3 XML) | Send every `upload_headers` entry unchanged, send exactly `size_bytes` bytes, and add no other headers. |
| PUT | `403` | `AccessDenied`, request expired (S3 XML) | `upload_url` is older than 24 hours. Create a new upload. |
| Complete | `409` | `resource_not_ready` | The `PUT` has not finished. Retry after it returns `200`. |
| Complete | `400` | `invalid_parameter` | The stored bytes do not match `content_type` or a type in the [size limits](#size-limits) table, the upload is more than 24 hours old, or `checksum_sha256` differs from the one sent at create. Create a new upload. |
| Complete | `404` | `asset_not_found` | Unknown `asset_id`, or one from another workspace. |

See [Error codes](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md) for the response envelope.


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