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

curl -X POST https://api.heygen.com/v3/assets \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./my-photo.png"
Response
{
  "data": {
    "asset_id": "ast_abc123",
    "url": "https://files.heygen.com/asset/ast_abc123.png",
    "mime_type": "image/png",
    "size_bytes": 204800
  }
}

​
Supported File Types

CategoryFormats
ImagePNG, JPEG
VideoMP4, WebM
AudioMP3, WAV
DocumentPDF
Max file size: 32 MB. MIME type is auto-detected from file bytes.

​
Using Assets

Once uploaded, reference the asset_id anywhere the API accepts asset inputs: 
// In POST /v3/video-agents (file attachments)
{
  "prompt": "Explain this diagram",
  "files": [{ "type": "asset_id", "asset_id": "ast_abc123" }]
}

// In POST /v3/avatars (photo avatar)
{
  "type": "photo",
  "name": "My Avatar",
  "file": { "type": "asset_id", "asset_id": "ast_abc123" }
}
Anywhere that accepts an asset also accepts a direct URL ({"type": "url", "url": "https://..."}) or base64 ({"type": "base64", "media_type": "image/png", "data": "..."}). Use asset_id when you need to reuse the same file across multiple requests.