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

# Assets Overview

> Upload images, video, audio, PDFs, and HyperFrames zips to HeyGen once and reference them by asset_id in any video, avatar, translation, or lipsync request. Pick an upload method, pass files to endpoints, and manage asset lifetime.

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

An asset is a file stored in your HeyGen workspace. Upload it once, get an `asset_id`, and pass that ID to any endpoint that takes a file, such as [`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session), [`POST /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar), or [`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/hyperframes).

## Choose an upload method

| Method | Endpoint | Max size | Use it for |
| - | - | - | - |
| [Simple upload](https://heygen-1fa696a7.mintlify.site/docs/upload-assets.md) | `POST /v3/assets` | 50 MB for video, audio, PDF; 32 MB for images | Small files in one `multipart/form-data` request. |
| [Direct upload to S3](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md) | `POST /v3/assets/direct-uploads` | 200 MB for video, image, PDF; 1.5 GB for audio; 1 GiB for zip | Large files, avatar training footage, and HyperFrames projects. Bytes go straight to S3. |
| [Batch direct upload](https://heygen-1fa696a7.mintlify.site/batch-assets.md) | `POST /v3/assets/direct-uploads/batches` | Same as direct upload, up to 100 files | Many files at once, uploaded in parallel and finalized with one call. |

Every method takes common image, video, audio, PDF, and SRT formats. Direct upload also takes ZIP for HyperFrames projects. Each method's page lists its exact types.

## Pass a file to an endpoint

Every file input accepts one of three shapes:

| Shape | Syntax | Use it when |
| - | - | - |
| Asset ID | `{ "type": "asset_id", "asset_id": "..." }` | You uploaded the file here. Reusable across requests, and the only option above 32 MB. |
| URL | `{ "type": "url", "url": "https://..." }` | The file is already hosted on a public HTTPS URL. |
| Base64 | `{ "type": "base64", "media_type": "image/png", "data": "..." }` | The file is a few MB and you want a self-contained request. |

```json theme={null}
{
  "prompt": "Explain this diagram",
  "files": [{ "type": "asset_id", "asset_id": "0104ec0f73f4422090eeddd72164f68d" }]
}
```

### Size limits by input

| Input | Images | Video, audio, PDF |
| - | - | - |
| `url` | 16 MB | 32 MB |
| `base64` (decoded size) | 5 MB | 16 MB |
| `asset_id` from [simple upload](https://heygen-1fa696a7.mintlify.site/docs/upload-assets.md) | 32 MB | 50 MB |
| `asset_id` from [direct upload](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md) | 200 MB | 200 MB (audio 1.5 GB) |

A `url` must use HTTPS, download without extra headers, return the file directly (redirects are not followed) with a `Content-Type` header, and stay valid until HeyGen fetches it. Signed URLs, such as S3 or Google Cloud Storage presigned URLs, follow the same limits. For anything larger, upload with [direct upload](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md) and pass the `asset_id`.

### Where assets are accepted

| Endpoint | Use |
| - | - |
| [`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session) | Reference images, slides, video clips, and audio. Follow-up files go to [`POST /v3/video-agents/{session_id}`](https://heygen-1fa696a7.mintlify.site/reference/send-message-or-request-revision). |
| [`POST /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar) | A photo for a [photo avatar](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-photo.md), or training footage for a [digital twin](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-video.md). Twin footage is usually over 32 MB, so use [direct upload](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md). |
| [`POST /v3/avatars/{group_id}/consent`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-consent) | A recorded [consent video](https://heygen-1fa696a7.mintlify.site/docs/avatar-consent.md). |
| [`POST /v3/video-translations`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation) | Source video or custom audio for [Video Translation](https://heygen-1fa696a7.mintlify.site/docs/video-translate.md). |
| [`POST /v3/lipsyncs`](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync) | Source video and replacement audio for [Lipsync](https://heygen-1fa696a7.mintlify.site/lipsync-speed.md). |
| [`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/hyperframes) | A zipped HyperFrames project. |

## Manage assets

| Task | Endpoint |
| - | - |
| List a member's assets, newest first (beta) | `GET /v3/assets` |
| Get one asset's metadata and URL | [`GET /v3/assets/{asset_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-asset) |
| Check up to 100 assets or batches | [`GET /v3/assets/statuses`](https://heygen-1fa696a7.mintlify.site/reference/bulk-asset-statuses) |
| Organize assets into folders | [Folders](https://heygen-1fa696a7.mintlify.site/folders.md) |
| Delete an asset | [`DELETE /v3/assets/{asset_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-asset) |

### Asset lifetime and deletion

An `asset_id` stays usable until you delete it. Upload a file once and reuse the same `asset_id` on every request and retry, for example when you resubmit a consent video after a rejected review. Only the presigned `upload_url` from direct upload expires (24 hours).

A deleted `asset_id` returns `asset_not_found` in later requests. Assets are independent of what you make from them: deleting an avatar group with [`DELETE /v3/avatars/{group_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-avatar-group) keeps its source files, and deleting an asset keeps the avatars and videos already made from it. Delete each source `asset_id` separately.

Files passed to other endpoints as a `url` or base64 are also saved as assets in your workspace, but those calls do not return the new `asset_id`. If you will need to delete a source file later, upload it first and pass its `asset_id`.


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