An asset is a file stored in your HeyGen workspace. Upload it once, get an asset_id, and pass that ID to any endpoint that takes a file, such as POST /v3/video-agents, POST /v3/avatars, or POST /v3/hyperframes/renders.
Choose an upload method
Every method takes common image, video, audio, PDF, and SRT formats. Direct upload also takes ZIP for HyperFrames projects. Each method’s page lists its exact types.
Pass a file to an endpoint
Every file input accepts one of three shapes:Size limits by input
A
url must use HTTPS, download without extra headers, return the file directly (redirects are not followed) with a Content-Type header, and stay valid until HeyGen fetches it. Signed URLs, such as S3 or Google Cloud Storage presigned URLs, follow the same limits. For anything larger, upload with direct upload and pass the asset_id.
Where assets are accepted
Manage assets
Asset lifetime and deletion
Anasset_id stays usable until you delete it. Upload a file once and reuse the same asset_id on every request and retry, for example when you resubmit a consent video after a rejected review. Only the presigned upload_url from direct upload expires (24 hours).
A deleted asset_id returns asset_not_found in later requests. Assets are independent of what you make from them: deleting an avatar group with DELETE /v3/avatars/{group_id} keeps its source files, and deleting an asset keeps the avatars and videos already made from it. Delete each source asset_id separately.
Files passed 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 first and pass its asset_id.
