Models

Create HeyGen Video

Generates a scene with its sound from a prompt using HeyGen Video (heygen-video-1). Set mode to text_to_video, image_to_video or reference_to_video; reference-to-video takes up to fifteen references in total, and reference videos must be between 1:4 and 4:1. Returns 202 with a video_id; poll GET /v3/models/videos/. Send an Idempotency-Key to retry safely; without one, each submission creates a new generation. To have an avatar speak a script, use POST /v3/videos.

POST

models

videos

Create HeyGen Video

curl --request POST \
  --url https://api.heygen.com/v3/models/videos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "mode": "text_to_video",
  "model": "heygen-video-1",
  "prompt": "<string>",
  "end_user_id": "<string>",
  "prompt_enhancement": "quality",
  "resolution": "768p",
  "duration": 5,
  "aspect_ratio": "16:9",
  "seed": 2147483647,
  "callback_url": "<string>",
  "callback_id": "<string>"
}
'

import requests

url = "https://api.heygen.com/v3/models/videos"

payload = {
    "mode": "text_to_video",
    "model": "heygen-video-1",
    "prompt": "<string>",
    "end_user_id": "<string>",
    "prompt_enhancement": "quality",
    "resolution": "768p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "seed": 2147483647,
    "callback_url": "<string>",
    "callback_id": "<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({
    mode: 'text_to_video',
    model: 'heygen-video-1',
    prompt: '<string>',
    end_user_id: '<string>',
    prompt_enhancement: 'quality',
    resolution: '768p',
    duration: 5,
    aspect_ratio: '16:9',
    seed: 2147483647,
    callback_url: '<string>',
    callback_id: '<string>'
  })
};

fetch('https://api.heygen.com/v3/models/videos', 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/models/videos",
  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([
    'mode' => 'text_to_video',
    'model' => 'heygen-video-1',
    'prompt' => '<string>',
    'end_user_id' => '<string>',
    'prompt_enhancement' => 'quality',
    'resolution' => '768p',
    'duration' => 5,
    'aspect_ratio' => '16:9',
    'seed' => 2147483647,
    'callback_url' => '<string>',
    'callback_id' => '<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/models/videos"

	payload := strings.NewReader("{\n  \"mode\": \"text_to_video\",\n  \"model\": \"heygen-video-1\",\n  \"prompt\": \"<string>\",\n  \"end_user_id\": \"<string>\",\n  \"prompt_enhancement\": \"quality\",\n  \"resolution\": \"768p\",\n  \"duration\": 5,\n  \"aspect_ratio\": \"16:9\",\n  \"seed\": 2147483647,\n  \"callback_url\": \"<string>\",\n  \"callback_id\": \"<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/models/videos")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mode\": \"text_to_video\",\n  \"model\": \"heygen-video-1\",\n  \"prompt\": \"<string>\",\n  \"end_user_id\": \"<string>\",\n  \"prompt_enhancement\": \"quality\",\n  \"resolution\": \"768p\",\n  \"duration\": 5,\n  \"aspect_ratio\": \"16:9\",\n  \"seed\": 2147483647,\n  \"callback_url\": \"<string>\",\n  \"callback_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/models/videos")

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  \"mode\": \"text_to_video\",\n  \"model\": \"heygen-video-1\",\n  \"prompt\": \"<string>\",\n  \"end_user_id\": \"<string>\",\n  \"prompt_enhancement\": \"quality\",\n  \"resolution\": \"768p\",\n  \"duration\": 5,\n  \"aspect_ratio\": \"16:9\",\n  \"seed\": 2147483647,\n  \"callback_url\": \"<string>\",\n  \"callback_id\": \"<string>\"\n}"

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

{
  "data": {
    "video_id": "<string>",
    "status": "pending",
    "input_video_duration": 7.5
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Provide at least one reference image, video, or audio recording.",
    "param": "reference_images",
    "doc_url": null
  }
}

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

{
  "error": {
    "code": "insufficient_credit",
    "message": "Insufficient credits for the video and its references. Add credits or use a shorter video or fewer references.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "asset_not_found",
    "message": "Asset not found.",
    "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
  }
}

{
  "error": {
    "code": "resource_not_ready",
    "message": "Asset ingestion is temporarily unavailable. Retry with the same Idempotency-Key."
  }
}

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

TextToVideoRequest
ImageToVideoRequest
ReferenceToVideoRequest

Body of POST /v3/models/videos: one schema per generation mode, selected by the required mode field.

mode

string

required

Generate from the prompt alone.

Allowed value: "text_to_video"

model

string

required

Required video generation model. Only heygen-video-1 is supported.

Allowed value: "heygen-video-1"

prompt

string

required

Instructions for the video to generate. At most 16,000 Unicode characters.

Required string length: 1 - 16000

end_user_id

string | null

Stable, opaque end-user identifier in your application, scoped to the authenticated workspace. Use 1–128 non-whitespace characters without personal information. Used for usage attribution and abuse investigation; does not change billing, authorization, or rate limits.

Required string length: 1 - 128

Pattern: ^\S+$

prompt_enhancement

enum<string>

default:quality

Prompt enhancement mode: turbo, quality, ultraquality, or disabled. Defaults to quality.

Available options:

turbo,

quality,

disabled,

ultraquality

resolution

enum<string>

default:768p

Output resolution: 480p, 768p, 1080p, or 2k. Defaults to 768p. At 1080p and 2k, text-to-video and reference-to-video require aspect_ratio 16:9 or 9:16; image-to-video follows the image proportions.

Available options:

480p,

768p,

1080p,

2k

duration

default:5

Requested video duration: whole seconds from 5 through 30, or auto. Defaults to 5 when omitted. Durations above 15 seconds require turbo or quality prompt enhancement. Auto estimates quoted speech with an 8-second minimum and the maximum supported by these settings. Over MCP, auto is capped at 15 seconds; use an explicit duration for longer output. Generation and billing use the resolved duration.

Required range: 5 <= x <= 30

aspect_ratio

enum<string>

default:16:9

Output aspect ratio for text-to-video. Defaults to 16:9.

Available options:

21:9,

16:9,

4:3,

1:1,

3:4,

9:16

seed

integer | null

Generation seed. A random seed is chosen when omitted.

Required range: 0 <= x <= 4294967295

callback_url

string | null

HTTPS webhook URL for the terminal generation event.

callback_id

string | null

Client tracking ID echoed in the terminal webhook event.

Maximum string length: 256

Response

Accepted — submission acknowledged; poll for completion.

data

CreateModelVideoResponse · object

Show child attributes

⌘I

Create HeyGen Video

curl --request POST \
  --url https://api.heygen.com/v3/models/videos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "mode": "text_to_video",
  "model": "heygen-video-1",
  "prompt": "<string>",
  "end_user_id": "<string>",
  "prompt_enhancement": "quality",
  "resolution": "768p",
  "duration": 5,
  "aspect_ratio": "16:9",
  "seed": 2147483647,
  "callback_url": "<string>",
  "callback_id": "<string>"
}
'

import requests

url = "https://api.heygen.com/v3/models/videos"

payload = {
    "mode": "text_to_video",
    "model": "heygen-video-1",
    "prompt": "<string>",
    "end_user_id": "<string>",
    "prompt_enhancement": "quality",
    "resolution": "768p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "seed": 2147483647,
    "callback_url": "<string>",
    "callback_id": "<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({
    mode: 'text_to_video',
    model: 'heygen-video-1',
    prompt: '<string>',
    end_user_id: '<string>',
    prompt_enhancement: 'quality',
    resolution: '768p',
    duration: 5,
    aspect_ratio: '16:9',
    seed: 2147483647,
    callback_url: '<string>',
    callback_id: '<string>'
  })
};

fetch('https://api.heygen.com/v3/models/videos', 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/models/videos",
  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([
    'mode' => 'text_to_video',
    'model' => 'heygen-video-1',
    'prompt' => '<string>',
    'end_user_id' => '<string>',
    'prompt_enhancement' => 'quality',
    'resolution' => '768p',
    'duration' => 5,
    'aspect_ratio' => '16:9',
    'seed' => 2147483647,
    'callback_url' => '<string>',
    'callback_id' => '<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/models/videos"

	payload := strings.NewReader("{\n  \"mode\": \"text_to_video\",\n  \"model\": \"heygen-video-1\",\n  \"prompt\": \"<string>\",\n  \"end_user_id\": \"<string>\",\n  \"prompt_enhancement\": \"quality\",\n  \"resolution\": \"768p\",\n  \"duration\": 5,\n  \"aspect_ratio\": \"16:9\",\n  \"seed\": 2147483647,\n  \"callback_url\": \"<string>\",\n  \"callback_id\": \"<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/models/videos")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mode\": \"text_to_video\",\n  \"model\": \"heygen-video-1\",\n  \"prompt\": \"<string>\",\n  \"end_user_id\": \"<string>\",\n  \"prompt_enhancement\": \"quality\",\n  \"resolution\": \"768p\",\n  \"duration\": 5,\n  \"aspect_ratio\": \"16:9\",\n  \"seed\": 2147483647,\n  \"callback_url\": \"<string>\",\n  \"callback_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/models/videos")

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  \"mode\": \"text_to_video\",\n  \"model\": \"heygen-video-1\",\n  \"prompt\": \"<string>\",\n  \"end_user_id\": \"<string>\",\n  \"prompt_enhancement\": \"quality\",\n  \"resolution\": \"768p\",\n  \"duration\": 5,\n  \"aspect_ratio\": \"16:9\",\n  \"seed\": 2147483647,\n  \"callback_url\": \"<string>\",\n  \"callback_id\": \"<string>\"\n}"

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

{
  "data": {
    "video_id": "<string>",
    "status": "pending",
    "input_video_duration": 7.5
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Provide at least one reference image, video, or audio recording.",
    "param": "reference_images",
    "doc_url": null
  }
}

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

{
  "error": {
    "code": "insufficient_credit",
    "message": "Insufficient credits for the video and its references. Add credits or use a shorter video or fewer references.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "asset_not_found",
    "message": "Asset not found.",
    "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
  }
}

{
  "error": {
    "code": "resource_not_ready",
    "message": "Asset ingestion is temporarily unavailable. Retry with the same Idempotency-Key."
  }
}

Video Agent

Brand

Avatars

Audio

Models

Videos

Templates

Video Translate

Lipsync

HyperFrames

User

API Keys

Webhooks

Folders

Assets

AI Clipping

Filler Word Removal

Batches

Video Translation Batches

Lipsync Batches

Asset Batches

Create HeyGen Video

Authorizations

Headers

Body

Response