Skip to main content
Upload images, videos, audio, or PDFs to get an asset_id you can reference in other endpoints — like POST /v3/video-agents, POST /v3/videos, or POST /v3/avatars.

​
Upload an Asset

Response

​
Supported File Types

Max file size: 32 MB. MIME type is auto-detected from file bytes. For larger files, use the direct upload flow below.

​
Direct Upload for Large Files

POST /v3/assets proxies file bytes through the API, which is why it’s capped at 32 MB. For larger files, use the presigned direct upload flow — three required steps:
  1. POST /v3/assets/direct-uploads with filename, content_type, and exact size_bytes → returns asset_id, a presigned upload_url, and upload_headers.
  2. PUT the raw file bytes to upload_url, sending upload_headers verbatim, before the URL expires (expires_in_seconds).
  3. POST /v3/assets/{asset_id}/complete to finalize. Idempotent. The asset_id is not usable until this step succeeds.
The per-upload cap for this flow is returned as max_bytes in the initialize response. See Upload Assets for full examples in Python and Node.js. To upload up to 100 files in one call, use the batch variant of this flow.

​
Using Assets

Once uploaded, reference the asset_id anywhere the API accepts asset inputs:
Anywhere that accepts an asset also accepts a direct URL ({"type": "url", "url": "https://..."}) or base64 ({"type": "base64", "media_type": "image/png", "data": "..."}). The 32 MB per-file limit applies to URL inputs too — for larger files, upload via the direct upload flow and pass the asset_id. Use asset_id when you need to reuse the same file across multiple requests.