Create HeyGen Image

POST

models

images

Create HeyGen Image

curl --request POST \
  --url https://api.heygen.com/v3/models/images \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "model": "heygen-image-1",
  "identity_images": [
    {
      "type": "url",
      "url": "<string>"
    }
  ],
  "reference_images": [
    {
      "type": "url",
      "url": "<string>"
    }
  ],
  "mode": "identity_remix",
  "num_images": 1,
  "seed": 2147483647
}
'

import requests

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

payload = {
    "model": "heygen-image-1",
    "identity_images": [
        {
            "type": "url",
            "url": "<string>"
        }
    ],
    "reference_images": [
        {
            "type": "url",
            "url": "<string>"
        }
    ],
    "mode": "identity_remix",
    "num_images": 1,
    "seed": 2147483647
}
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({
    model: 'heygen-image-1',
    identity_images: [{type: 'url', url: '<string>'}],
    reference_images: [{type: 'url', url: '<string>'}],
    mode: 'identity_remix',
    num_images: 1,
    seed: 2147483647
  })
};

fetch('https://api.heygen.com/v3/models/images', 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/images",
  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([
    'model' => 'heygen-image-1',
    'identity_images' => [
        [
                'type' => 'url',
                'url' => '<string>'
        ]
    ],
    'reference_images' => [
        [
                'type' => 'url',
                'url' => '<string>'
        ]
    ],
    'mode' => 'identity_remix',
    'num_images' => 1,
    'seed' => 2147483647
  ]),
  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/images"

	payload := strings.NewReader("{\n  \"model\": \"heygen-image-1\",\n  \"identity_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"reference_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"mode\": \"identity_remix\",\n  \"num_images\": 1,\n  \"seed\": 2147483647\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/images")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"heygen-image-1\",\n  \"identity_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"reference_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"mode\": \"identity_remix\",\n  \"num_images\": 1,\n  \"seed\": 2147483647\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"model\": \"heygen-image-1\",\n  \"identity_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"reference_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"mode\": \"identity_remix\",\n  \"num_images\": 1,\n  \"seed\": 2147483647\n}"

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

{
  "data": {
    "generation_id": "<string>",
    "status": "pending"
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Video not found",
    "param": "<string>",
    "doc_url": "<string>",
    "errors": [
      {
        "code": "unknown_node_type",
        "message": "Unknown node type",
        "node_id": "<string>",
        "port": "<string>",
        "path": "<string>"
      }
    ]
  }
}

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

{
  "error": {
    "code": "resource_not_found",
    "message": "Image generation 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
  }
}

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

model

string

required

Required identity-focused image model. Only heygen-image-1 is supported.

Allowed value: "heygen-image-1"

identity_images

(AssetUrl · object | AssetId · object | AssetBase64 · object)[]

required

One to five images of the identity to preserve.

Required array length: 1 - 5 elements

Asset input via publicly accessible HTTPS URL.

AssetUrl
AssetId
AssetBase64

Show child attributes

reference_images

(AssetUrl · object | AssetId · object | AssetBase64 · object)[]

required

Supply exactly one image whose clothing, pose, composition, and background should guide the result.

Required array length: 1 element

Asset input via publicly accessible HTTPS URL.

AssetUrl
AssetId
AssetBase64

Show child attributes

mode

string

default:identity_remix

Generation operation. Only identity_remix is supported. Defaults to identity_remix when omitted.

Allowed value: "identity_remix"

aspect_ratio

enum<string> | null

Output aspect ratio. Omit to match the reference image after EXIF orientation. Explicit presets are exact; inferred ratios round to the nearest pixel. Output resolution follows the model's canvas policy; read width and height from each result.

Available options:

1:1,

2:3,

3:2,

3:4,

4:3,

4:5,

5:4,

9:16,

16:9

num_images

integer

default:1

Number of images to generate in this job. Supports one to five.

Required range: 1 <= x <= 5

seed

integer | null

Seed for the first image. Each subsequent image increments the seed by one. A random seed is chosen when omitted.

Required range: 0 <= x <= 4294967295

Response

Accepted — submission acknowledged; poll for completion.

data

CreateImageGenerationResponse · object

Show child attributes

⌘I

Create HeyGen Image

curl --request POST \
  --url https://api.heygen.com/v3/models/images \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "model": "heygen-image-1",
  "identity_images": [
    {
      "type": "url",
      "url": "<string>"
    }
  ],
  "reference_images": [
    {
      "type": "url",
      "url": "<string>"
    }
  ],
  "mode": "identity_remix",
  "num_images": 1,
  "seed": 2147483647
}
'

import requests

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

payload = {
    "model": "heygen-image-1",
    "identity_images": [
        {
            "type": "url",
            "url": "<string>"
        }
    ],
    "reference_images": [
        {
            "type": "url",
            "url": "<string>"
        }
    ],
    "mode": "identity_remix",
    "num_images": 1,
    "seed": 2147483647
}
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({
    model: 'heygen-image-1',
    identity_images: [{type: 'url', url: '<string>'}],
    reference_images: [{type: 'url', url: '<string>'}],
    mode: 'identity_remix',
    num_images: 1,
    seed: 2147483647
  })
};

fetch('https://api.heygen.com/v3/models/images', 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/images",
  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([
    'model' => 'heygen-image-1',
    'identity_images' => [
        [
                'type' => 'url',
                'url' => '<string>'
        ]
    ],
    'reference_images' => [
        [
                'type' => 'url',
                'url' => '<string>'
        ]
    ],
    'mode' => 'identity_remix',
    'num_images' => 1,
    'seed' => 2147483647
  ]),
  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/images"

	payload := strings.NewReader("{\n  \"model\": \"heygen-image-1\",\n  \"identity_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"reference_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"mode\": \"identity_remix\",\n  \"num_images\": 1,\n  \"seed\": 2147483647\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/images")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"heygen-image-1\",\n  \"identity_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"reference_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"mode\": \"identity_remix\",\n  \"num_images\": 1,\n  \"seed\": 2147483647\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"model\": \"heygen-image-1\",\n  \"identity_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"reference_images\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"mode\": \"identity_remix\",\n  \"num_images\": 1,\n  \"seed\": 2147483647\n}"

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

{
  "data": {
    "generation_id": "<string>",
    "status": "pending"
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Video not found",
    "param": "<string>",
    "doc_url": "<string>",
    "errors": [
      {
        "code": "unknown_node_type",
        "message": "Unknown node type",
        "node_id": "<string>",
        "port": "<string>",
        "path": "<string>"
      }
    ]
  }
}

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

{
  "error": {
    "code": "resource_not_found",
    "message": "Image generation 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
  }
}

Video Agent

Brand

Avatars

Audio

Voices

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

Authorizations

Headers

Body

Response