Skip to main content
POST
/
v3
/
assets
/
direct-uploads
Create Asset Upload
curl --request POST \
  --url https://api.heygen.com/v3/assets/direct-uploads \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "filename": "<string>",
  "content_type": "<string>",
  "size_bytes": 123,
  "checksum_sha256": "<string>"
}
'
{
  "data": {
    "asset_id": "<string>",
    "upload_url": "<string>",
    "upload_headers": {},
    "expires_in_seconds": 123,
    "max_bytes": 123,
    "status": "<string>"
  }
}

Authorizations

​
x-api-key
string
header
required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

​
Idempotency-Key
string

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Required string length: 1 - 255
Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json

Request to begin a presigned direct-to-S3 upload (POST /v3/assets/direct-uploads).

​
filename
string
required

Original filename for reference/metadata. The stored object's extension is derived from content_type.

​
content_type
string
required

Declared MIME type (e.g. 'video/mp4'). Verified against the stored bytes at completion.

​
size_bytes
integer
required

Exact byte size of the file. Signed into the upload URL so it cannot be exceeded.

​
checksum_sha256
string | null

Optional SHA256 of the file as hex. When provided, S3 enforces it on upload.

Response

Successful response

​
data
CreateAssetUploadResponse · object

Presigned upload instructions.