Upload Assets

The Assets API lets you upload files to HeyGen and receive an asset_id you can reference in other endpoints — including Video Agent, Avatar creation, Video Translation, and Lipsync. There are two ways to upload:

POST /v3/assets — a single multipart/form-data request. Simplest option, capped at 32 MB.
Direct upload — a presigned-URL flow for files larger than 32 MB, up to 200 MB per video, image, or PDF file and 1.5 GB per audio file. The file bytes go straight to storage and never pass through the API.

Upload via `POST /v3/assets`

Full schema: POST /v3/assets. Upload a file using multipart/form-data — the MIME type is auto-detected from file bytes.

Constraints

Constraint	Value
Max file size	32 MB — for larger files, use direct upload
Max file size (direct upload)	200 MB for video, image, PDF; 1.5 GB for audio
Supported images	png, jpeg
Supported video	mp4, webm
Supported audio	mp3, wav
Other	pdf

Example request

curl -X POST "https://api.heygen.com/v3/assets" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -F "file=@./product-screenshot.png"

import requests

with open("product-screenshot.png", "rb") as f:
    resp = requests.post(
        "https://api.heygen.com/v3/assets",
        headers={"X-Api-Key": HEYGEN_API_KEY},
        files={"file": ("product-screenshot.png", f, "image/png")},
    )

asset = resp.json()["data"]
print(asset["asset_id"])

const fs = require("fs");
const FormData = require("form-data");

const form = new FormData();
form.append("file", fs.createReadStream("./product-screenshot.png"));

const resp = await fetch("https://api.heygen.com/v3/assets", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.HEYGEN_API_KEY,
    ...form.getHeaders(),
  },
  body: form,
});
const { data } = await resp.json();
console.log(data.asset_id);

Response

{
  "data": {
    "asset_id": "asset_abc123def456",
    "url": "https://files.heygen.ai/assets/asset_abc123def456.png",
    "mime_type": "image/png",
    "size_bytes": 245760
  }
}

Field	Type	Description
`asset_id`	string	Unique identifier to reference this file in other API calls. Does not expire; see Asset lifetime and deletion.
`url`	string	Public URL of the uploaded file.
`mime_type`	string	Detected MIME type.
`size_bytes`	integer	File size in bytes.

Upload large files (direct upload)

For files larger than 32 MB, use the direct upload flow. Direct upload accepts files up to 200 MB (209,715,200 bytes) for video, image, and PDF, and up to 1.5 GB for audio. The limit for your file type is also returned as max_bytes. It is a three-step process — all three steps are required; the asset_id is not usable until you call the complete endpoint:

Initialize the upload

Call POST /v3/assets/direct-uploads with the file’s name, MIME type, and exact byte size. The response contains an asset_id, a presigned upload_url, and upload_headers.

PUT the file bytes

Send the raw file bytes to upload_url with an HTTP PUT, including every header from upload_headers verbatim. The URL expires after expires_in_seconds, and the byte size is signed into it — the upload fails if the file doesn’t match the declared size_bytes.

Complete the upload

Call POST /v3/assets/{asset_id}/complete to finalize the asset. This step is idempotent — repeated calls return the same finalized asset. The asset_id is now usable anywhere the API accepts assets. The complete response returns status: "processing". You do not need to wait for it to change; pass the asset_id to the next request (for example POST /v3/avatars) right away.

Example

# Step 1: Initialize
SIZE=$(stat -f%z ./footage.mp4)  # use `stat -c%s` on Linux
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\": \"footage.mp4\", \"content_type\": \"video/mp4\", \"size_bytes\": $SIZE}")

ASSET_ID=$(echo "$INIT" | jq -r '.data.asset_id')
UPLOAD_URL=$(echo "$INIT" | jq -r '.data.upload_url')

# Step 2: PUT the raw bytes to the presigned URL,
# passing every header from data.upload_headers verbatim
HEADER_ARGS=$(echo "$INIT" | jq -r '.data.upload_headers | to_entries[] | "-H \"\(.key): \(.value)\""' | tr '\n' ' ')
eval curl -X PUT "$UPLOAD_URL" $HEADER_ARGS --upload-file ./footage.mp4

# Step 3: Complete
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 '{}'

import os
import requests

file_path = "footage.mp4"

# Step 1: Initialize
init = requests.post(
    "https://api.heygen.com/v3/assets/direct-uploads",
    headers={"X-Api-Key": HEYGEN_API_KEY},
    json={
        "filename": os.path.basename(file_path),
        "content_type": "video/mp4",
        "size_bytes": os.path.getsize(file_path),
    },
).json()["data"]

# Step 2: PUT the raw bytes to the presigned URL
with open(file_path, "rb") as f:
    put_resp = requests.put(init["upload_url"], data=f, headers=init["upload_headers"])
put_resp.raise_for_status()

# Step 3: Complete
asset = requests.post(
    f"https://api.heygen.com/v3/assets/{init['asset_id']}/complete",
    headers={"X-Api-Key": HEYGEN_API_KEY},
    json={},
).json()["data"]

print(asset["asset_id"], asset["status"])

const fs = require("fs");

const filePath = "./footage.mp4";
const { size } = fs.statSync(filePath);

// Step 1: Initialize
const initResp = await fetch("https://api.heygen.com/v3/assets/direct-uploads", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.HEYGEN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    filename: "footage.mp4",
    content_type: "video/mp4",
    size_bytes: size,
  }),
});
const init = (await initResp.json()).data;

// Step 2: PUT the raw bytes to the presigned URL
await fetch(init.upload_url, {
  method: "PUT",
  headers: init.upload_headers,
  body: fs.readFileSync(filePath),
});

// Step 3: Complete
const completeResp = await fetch(
  `https://api.heygen.com/v3/assets/${init.asset_id}/complete`,
  {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  }
);
const asset = (await completeResp.json()).data;
console.log(asset.asset_id, asset.status);

Initialize response fields

Field	Type	Description
`asset_id`	string	Reusable asset identifier. Becomes usable after the complete step.
`upload_url`	string	Presigned URL. `PUT` the raw file bytes here.
`upload_headers`	object	Headers that must be sent verbatim on the `PUT` request.
`expires_in_seconds`	integer	Seconds until `upload_url` expires.
`max_bytes`	integer	Maximum upload size in bytes for this content type: 209,715,200 (200 MiB) for video, image, and PDF files, 1,500,000,000 (1.5 GB) for audio files. A larger `size_bytes` is rejected at initialize.
`status`	string	Always `pending_upload` at this stage.

Calling complete before the PUT has finished returns a 409 conflict (“Uploaded object not found yet”). Retry after the PUT returns 200. You can optionally pass checksum_sha256 (hex) at both the initialize and complete steps to have the stored bytes verified end to end.

Use assets in Video Agent

Once uploaded, reference the asset_id in the files array when creating a video:

{
  "prompt": "Create a product demo using the attached screenshots",
  "files": [
    { "type": "asset_id", "asset_id": "asset_abc123def456" },
    { "type": "asset_id", "asset_id": "asset_ghi789jkl012" }
  ]
}

Three ways to provide files

Video Agent and other endpoints accept files in three formats. Use whichever is most convenient for your workflow:

Asset ID

Upload once, reference by ID. Best for files you reuse across multiple videos.

HTTPS URL

Point to a publicly accessible HTTPS URL. No upload step needed, HeyGen fetches the file directly. Limits: 16 MB for images, 32 MB for video, audio, and PDF.

Base64

Inline the file content as a base64-encoded string. Useful for small files or when you want a self-contained request.

Format comparison

Format	Syntax	When to use
Asset ID	`{ "type": "asset_id", "asset_id": "asset_..." }`	Pre-uploaded files, reusable across requests. Only option for files over 32 MB (via direct upload).
URL	`{ "type": "url", "url": "https://..." }`	Files already hosted publicly, within the size limits below.
Base64	`{ "type": "base64", "media_type": "image/png", "data": "iVBOR..." }`	Small files, self-contained requests, no hosting needed.

Size limits by input

Input	Images	Video, audio, PDF
`url`	16 MB	32 MB
`base64` (decoded size)	5 MB	16 MB
`asset_id` from `POST /v3/assets`	32 MB	32 MB
`asset_id` from direct upload	200 MB	200 MB (audio 1.5 GB)

URL inputs are capped at 16 MB for images and 32 MB for video, audio, and PDF. Pointing at a larger self-hosted file fails with Maximum size for URL inputs of type 'video/mp4' is 32 MB. For larger files, use direct upload and pass the resulting asset_id. Base64 encoding additionally inflates payload size by ~33%, so prefer the other two formats for anything beyond a few MB.

Signed URLs (for example S3 or Google Cloud Storage presigned URLs) work like any other url input and have the same size limits. Signing a URL does not raise the limit. The URL must use HTTPS, be downloadable without extra headers, return the file directly (redirects are not followed) with a Content-Type header, and still be valid when HeyGen fetches it. For files over the URL limit, or when you cannot guarantee the link stays valid, use direct upload and pass the asset_id.

Where assets can be used

The asset_id format is accepted anywhere the API takes file inputs:

Endpoint	Use case
`POST /v3/video-agents`	Attach reference files (images, slides, video clips, audio).
`POST /v3/video-agents/{session_id}`	Send additional files in follow-up messages — see Interactive Sessions.
`POST /v3/avatars`	Provide a photo for a photo avatar, or training footage for a digital twin (consent videos go to `POST /v3/avatars/{group_id}/consent`). Twin footage (15 to 600 seconds, about 2 minutes of natural talking at 1080p recommended) is usually larger than 32 MB, so upload it with direct upload, keep the file under 200 MB, and pass the `asset_id`. See Create Avatar.
`POST /v3/video-translations`	Provide source video or custom audio — see Video Translation.
`POST /v3/lipsyncs`	Provide source video and/or replacement audio — see Lipsync.

Asset lifetime and deletion

An asset_id does not expire. It stays usable in any request until you delete it, so upload a file once and reuse the same asset_id on every retry, for example when you retry POST /v3/avatars or resubmit a consent video with POST /v3/avatars/{group_id}/consent after a rejected review. You do not need to upload the file again. Only the presigned upload_url from direct upload is time-limited (expires_in_seconds, 24 hours). The asset_id it returns becomes usable after the complete step and then follows the same rule. Delete an asset with DELETE /v3/assets/{asset_id}:

curl

curl -X DELETE "https://api.heygen.com/v3/assets/asset_abc123def456" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

A deleted asset_id returns asset_not_found in later requests. Assets are separate from the avatars, videos, and translations you create from them. Deleting an avatar group with DELETE /v3/avatars/{group_id} removes the avatar and all its looks, but not the files you uploaded to create it, and deleting an asset does not affect avatars or videos already made from it. To remove an uploaded training footage or consent video file, call DELETE /v3/assets/{asset_id} for each asset_id. Files you pass 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 here first and pass its asset_id.

Example: Upload then generate

A complete workflow — upload a PDF, then use it to generate a video:

# Step 1: Upload the PDF
ASSET_ID=$(curl -s -X POST "https://api.heygen.com/v3/assets" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -F "file=@./quarterly-report.pdf" | jq -r '.data.asset_id')

echo "Uploaded asset: $ASSET_ID"

# Step 2: Generate a video using the uploaded PDF
curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"Summarize the key findings from this quarterly report in a 60-second video\",
    \"files\": [{ \"type\": \"asset_id\", \"asset_id\": \"$ASSET_ID\" }]
  }"

import requests

# Step 1: Upload
with open("quarterly-report.pdf", "rb") as f:
    upload_resp = requests.post(
        "https://api.heygen.com/v3/assets",
        headers={"X-Api-Key": HEYGEN_API_KEY},
        files={"file": f},
    )
asset_id = upload_resp.json()["data"]["asset_id"]

# Step 2: Generate
gen_resp = requests.post(
    "https://api.heygen.com/v3/video-agents",
    headers={"X-Api-Key": HEYGEN_API_KEY},
    json={
        "prompt": "Summarize the key findings from this quarterly report in a 60-second video",
        "files": [{"type": "asset_id", "asset_id": asset_id}],
    },
)
session = gen_resp.json()["data"]

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Avatar Management

Voice Management

Video Translation

Lipsync

Tools

Asset Management

Batches

Webhook

Limits

Socials

For Agents

Integrations

Upload via `POST /v3/assets`

Constraints

Example request

Response

Upload large files (direct upload)

Example

Initialize response fields

Use assets in Video Agent

Three ways to provide files

Asset ID

HTTPS URL

Base64

Format comparison

Size limits by input

Where assets can be used

Asset lifetime and deletion

Example: Upload then generate

​Upload via POST /v3/assets

​Constraints

​Example request

​Response

​Upload large files (direct upload)

​Example

​Initialize response fields

​Use assets in Video Agent

​Three ways to provide files

Asset ID

HTTPS URL

Base64

​Format comparison

​Size limits by input

​Where assets can be used

​Asset lifetime and deletion

​Example: Upload then generate

Upload via `POST /v3/assets`

Constraints

Example request

Response

Upload large files (direct upload)

Example

Initialize response fields

Use assets in Video Agent

Three ways to provide files

Format comparison

Size limits by input

Where assets can be used

Asset lifetime and deletion

Example: Upload then generate