| name | heygen-asset-upload |
| description | Upload images, videos, audio, or PDFs to HeyGen and return reusable asset IDs. Use when the user wants to upload local files for HeyGen, prepare assets for Video Agent, avatars, image-to-video, video translation, or any HeyGen endpoint that accepts asset_id file inputs. |
HeyGen Asset Upload
Rules
- Use this skill for HeyGen
POST /v3/assets uploads.
- Read
.env from the repo root before running scripts. Require HEYGEN_API_KEY; never print the key.
- Prefer uploading local files once and reusing returned
asset_id values for later HeyGen calls.
- Check file constraints before upload: max 32 MB; images
png/jpeg; video mp4/webm; audio mp3/wav; PDFs supported.
- For Vietnamese user-facing output, write Vietnamese with accents. Keep API fields, endpoint paths, and enum values unchanged.
API
POST https://api.heygen.com/v3/assets
Header: X-Api-Key: <HEYGEN_API_KEY>
Body: multipart/form-data file=@<path>
Successful responses include:
{
"data": {
"asset_id": "asset_abc123def456",
"url": "https://files.heygen.ai/assets/asset_abc123def456.png",
"mime_type": "image/png",
"size_bytes": 245760
}
}
Script
Upload one or more files:
python skills/heygen-asset-upload/scripts/heygen_asset_upload.py upload \
--env-file .env \
--files jobs/<job_id>/input/raw_assets/images/person.jpg,jobs/<job_id>/input/raw_assets/audio/narration.mp3 \
--output jobs/<job_id>/source/heygen_assets.json
Print only the compact JSON response:
python skills/heygen-asset-upload/scripts/heygen_asset_upload.py upload \
--env-file .env \
--files path/to/file.png
Outputs
When --output is provided, the script writes:
{
"assets": [
{
"path": "...",
"asset_id": "asset_...",
"url": "https://...",
"mime_type": "image/png",
"size_bytes": 12345,
"response": {}
}
]
}
Use uploaded assets in HeyGen file inputs as:
{ "type": "asset_id", "asset_id": "asset_..." }
Troubleshooting
Missing HEYGEN_API_KEY: add it to .env or export it in the shell.File too large: HeyGen limits uploads to 32 MB; compress or provide a public HTTPS URL instead.Unsupported file type: convert to a supported format before upload.401: invalid or inactive HeyGen API key.400 / 422: inspect the saved response; confirm the file field is named exactly file.
Sources
