Simple Upload - HeyGen Documentation

POST /v3/assets uploads a file in one multipart/form-data request and returns an asset_id. For files over the limits below, use direct upload to S3. To pick a method or see where an asset_id can be used, start at the Assets overview.

Upload a file

The MIME type is detected from the file bytes.

Limits

File type	Formats	Max size
Image	PNG, JPEG	32 MB
Video	MP4, WebM	50 MB
Audio	MP3, WAV	50 MB
Document	PDF	50 MB
Subtitles	SRT	50 MB

Each file is checked against the content policy after upload. A blocked file is removed, and later requests for its asset_id return not found.

Example request

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

The response carries the asset_id, a public url of the uploaded file, the detected mime_type, and size_bytes; see the reference. The asset_id does not expire; see Asset lifetime and deletion.

Example: upload then generate

Upload a PDF, then pass its asset_id to Video Agent:

# 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')

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

⌘I