Asset Batches

Create Asset Upload Batch

Request up to 100 presigned direct-to-S3 upload URLs in a single call. Returns a batch_id and one upload slot per file (asset_id + presigned upload_url + required headers). PUT each file’s bytes to its upload_url, then call POST /v3/assets/complete/batches to finalize the whole batch. This is synchronous — no bytes flow through the API. Pass an Idempotency-Key header to make retries safe (the same key returns the same batch).

POST

assets

direct-uploads

batches

Create Asset Upload Batch

curl --request POST \
  --url https://api.heygen.com/v3/assets/direct-uploads/batches \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "files": [
    {
      "filename": "<string>",
      "content_type": "<string>",
      "size_bytes": 123,
      "checksum_sha256": "<string>"
    }
  ],
  "title": "<string>",
  "callback_url": "<string>"
}
'

import requests

url = "https://api.heygen.com/v3/assets/direct-uploads/batches"

payload = {
    "files": [
        {
            "filename": "<string>",
            "content_type": "<string>",
            "size_bytes": 123,
            "checksum_sha256": "<string>"
        }
    ],
    "title": "<string>",
    "callback_url": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    files: [
      {
        filename: '<string>',
        content_type: '<string>',
        size_bytes: 123,
        checksum_sha256: '<string>'
      }
    ],
    title: '<string>',
    callback_url: '<string>'
  })
};

fetch('https://api.heygen.com/v3/assets/direct-uploads/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/assets/direct-uploads/batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'files' => [
        [
                'filename' => '<string>',
                'content_type' => '<string>',
                'size_bytes' => 123,
                'checksum_sha256' => '<string>'
        ]
    ],
    'title' => '<string>',
    'callback_url' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/assets/direct-uploads/batches"

	payload := strings.NewReader("{\n  \"files\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_type\": \"<string>\",\n      \"size_bytes\": 123,\n      \"checksum_sha256\": \"<string>\"\n    }\n  ],\n  \"title\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.heygen.com/v3/assets/direct-uploads/batches")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"files\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_type\": \"<string>\",\n      \"size_bytes\": 123,\n      \"checksum_sha256\": \"<string>\"\n    }\n  ],\n  \"title\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/assets/direct-uploads/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"files\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_type\": \"<string>\",\n      \"size_bytes\": 123,\n      \"checksum_sha256\": \"<string>\"\n    }\n  ],\n  \"title\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "batch_id": "<string>",
    "items": [
      {
        "asset_id": "<string>",
        "upload_url": "<string>",
        "upload_headers": {},
        "expires_in_seconds": 123,
        "max_bytes": 123,
        "status": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid file(s) at index 3.",
    "param": "files",
    "doc_url": null
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or expired API key. Verify your x-api-key header.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "request_in_progress",
    "message": "A request with this Idempotency-Key is already in progress. Retry shortly.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the duration specified in the Retry-After header.",
    "param": null,
    "doc_url": null
  }
}

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

files

AssetUploadItem · object[]

required

Files to presign, same shape as POST /v3/assets/direct-uploads. Max 100 per batch.

Required array length: 1 - 100 elements

Show child attributes

title

string | null

Display name for the batch, shown in the HeyGen app.

callback_url

string | null

Reserved. Asset completion does not emit a webhook.

Response

Successful response

data

CreateAssetUploadBatchResponse · object

Show child attributes

⌘I

Create Asset Upload Batch

curl --request POST \
  --url https://api.heygen.com/v3/assets/direct-uploads/batches \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "files": [
    {
      "filename": "<string>",
      "content_type": "<string>",
      "size_bytes": 123,
      "checksum_sha256": "<string>"
    }
  ],
  "title": "<string>",
  "callback_url": "<string>"
}
'

import requests

url = "https://api.heygen.com/v3/assets/direct-uploads/batches"

payload = {
    "files": [
        {
            "filename": "<string>",
            "content_type": "<string>",
            "size_bytes": 123,
            "checksum_sha256": "<string>"
        }
    ],
    "title": "<string>",
    "callback_url": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    files: [
      {
        filename: '<string>',
        content_type: '<string>',
        size_bytes: 123,
        checksum_sha256: '<string>'
      }
    ],
    title: '<string>',
    callback_url: '<string>'
  })
};

fetch('https://api.heygen.com/v3/assets/direct-uploads/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/assets/direct-uploads/batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'files' => [
        [
                'filename' => '<string>',
                'content_type' => '<string>',
                'size_bytes' => 123,
                'checksum_sha256' => '<string>'
        ]
    ],
    'title' => '<string>',
    'callback_url' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/assets/direct-uploads/batches"

	payload := strings.NewReader("{\n  \"files\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_type\": \"<string>\",\n      \"size_bytes\": 123,\n      \"checksum_sha256\": \"<string>\"\n    }\n  ],\n  \"title\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.heygen.com/v3/assets/direct-uploads/batches")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"files\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_type\": \"<string>\",\n      \"size_bytes\": 123,\n      \"checksum_sha256\": \"<string>\"\n    }\n  ],\n  \"title\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/assets/direct-uploads/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"files\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_type\": \"<string>\",\n      \"size_bytes\": 123,\n      \"checksum_sha256\": \"<string>\"\n    }\n  ],\n  \"title\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "batch_id": "<string>",
    "items": [
      {
        "asset_id": "<string>",
        "upload_url": "<string>",
        "upload_headers": {},
        "expires_in_seconds": 123,
        "max_bytes": 123,
        "status": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid file(s) at index 3.",
    "param": "files",
    "doc_url": null
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or expired API key. Verify your x-api-key header.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "request_in_progress",
    "message": "A request with this Idempotency-Key is already in progress. Retry shortly.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the duration specified in the Retry-After header.",
    "param": null,
    "doc_url": null
  }
}

Video Agent

Brand

Avatars

Audio

Voices

Videos

Templates

Video Translate

Lipsync

HyperFrames

User

Webhooks

Assets

AI Clipping

Filler Word Removal

Batches

Video Translation Batches

Lipsync Batches

Asset Batches

Create Asset Upload Batch

Authorizations

Headers

Body

Response