HEheygen
Models

Create HeyGen Image

Changed on

Generate one to five portraits with identity_remix, the default and only supported mode. Provide one to five identity_images and exactly one item in reference_images. The output preserves the identity while following the reference image's clothing, pose, composition, and background. Returns a generation_id to poll. The job completes when all requested images are available; partial results are not returned.

post/v3/models/images

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/models/images
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

Idempotency-Keystring

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.

Request body

model'heygen-image-1' required

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

mode'identity_remix'

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

aspect_ratio'1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' nullable

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.

num_imagesinteger

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

seedinteger nullable

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

Response

Accepted — submission acknowledged; poll for completion.

Changes