Skip to main content
POST
Create HeyGen Image

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.

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.

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