Upload Assets

Upload images, video, audio, and PDFs to use as file inputs in Video Agent and other endpoints.

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, and video translation.

Upload an asset

POST https://api.heygen.com/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
Supported images	png, jpeg
Supported video	mp4, webm
Supported audio	mp3, wav
Other	pdf

Example request

curl

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

Response

{
  "data": {
    "asset_id": "asset_abc123def456",
    "url": "https://files.heygen.com/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.
url	string	Public URL of the uploaded file.
mime_type	string	Detected MIME type.
size_bytes	integer	File size in bytes.

---

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 URL. No upload step needed — HeyGen fetches the file directly.

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.
URL	{ "type": "url", "url": "https://..." }	Files already hosted publicly. Simplest option.
Base64	{ "type": "base64", "media_type": "image/png", "data": "iVBOR..." }	Small files, self-contained requests, no hosting needed.

Base64 encoding increases payload size by ~33%. For files larger than a few MB, prefer uploading via POST /v3/assets or providing a URL.

---

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/sessions	Attach files to interactive sessions.
POST /v3/video-agents/sessions/{id}/messages	Send additional files in follow-up messages.
POST /v3/avatars	Provide a photo or video for avatar creation.
POST /v3/video-translations	Provide source video or custom audio.

---

Example: Upload then generate

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

curl

# 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\" }]
  }"