> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HeyGen Image

> One identity, any scene. HeyGen Image keeps a person's face and takes the pose, clothing, light and setting from a reference image, on POST /v3/models/images.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-3.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=c8191ba4743fd85050f1af1a93ed4969)

One person. Six scenes she was never photographed in. HeyGen Image takes identity photos of a person and one reference image, and returns portraits that keep her face while following the reference's pose, clothing, light and setting.

## From one identity to any scene

Three photos of the HeyGen public avatar Serena went in as `identity_images`. Each scene below is one call with one `reference_images` entry, shown inset at the bottom left of its output. The reference's person never appears; only her pose, outfit and world do.

The six references are generated images, not photographs of real people. A reference can be a photo you own, a frame from a film, or a product shot with a model in it; it must contain exactly one person, or the job fails with `multiple_faces_detected`.

The scene, light, clothing and framing come from the reference. The face, hair, expression and gaze come from the identity photos: these three are studio portraits looking at the camera, so every output looks at the camera too. For candid results, use candid identity photos. For video, a still becomes the first frame of a [HeyGen Video](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md#modes) `image_to_video` clip; start the prompt with "Keep the person exactly as they appear in the first frame" and describe one camera move.

> [!WARNING]
>
> Generate people you have the right to generate: yourself, a consenting colleague, or a licensed HeyGen public avatar as here. A public photo is not a licence for someone's face.

## Build it with an agent

Not technical? Paste this into [Claude Code](https://claude.com/claude-code), [Codex](https://openai.com/codex/), or Cursor. Bring a few photos of the person and a few scene photos you own; it generates the set with you.

```text Prompt for your agent wrap theme={null}
I want a set of portraits of one person in six different scenes with the HeyGen API. I am not a developer, so run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.

Read these first and follow them exactly:
- https://developers.heygen.com/docs/models/heygen-image.md
- https://developers.heygen.com/docs/upload-assets.md
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)

Then take me through this, checking each step before the next:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me.
2. Identity. Ask me for one to five clear photos of the person I have the right to use, or offer to use a HeyGen public avatar from GET /v3/avatars?ownership=public. Upload the photos with POST /v3/assets and keep the asset_ids.
3. Scenes. Ask me for up to six scene photos I own, each showing exactly one person whose pose, clothing, light and setting I want. Check each one: one person, whole head in frame. Upload them with POST /v3/assets and keep the asset_ids. Tell me which aspect ratio from the Output table matches each photo.
4. Portraits. For each reference, call POST /v3/models/images with model heygen-image-1, my identity asset_ids, that one reference, the same aspect_ratio, and an Idempotency-Key. Poll GET /v3/models/images/{generation_id} until completed, download each PNG and show it to me. If a job fails with no_face_detected, tell me which input to replace. Offer a second seed for any scene I want to re-roll.

If a request fails, look the error code up in the Errors tables on those pages and tell me the fix. Never invent keys, IDs, or URLs; if something is missing, ask me for that one thing.
```

## The API

| | |
| - | - |
| Model | `heygen-image-1`, mode `identity_remix` (the only mode; omit it) |
| Create | [`POST /v3/models/images`](https://heygen-1fa696a7.mintlify.site/reference/create-heygen-image), returns `202` and a `generation_id` |
| Retrieve | [`GET /v3/models/images/{generation_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-heygen-image), poll until `completed` |
| Inputs | 1–5 `identity_images` of one person, exactly 1 `reference_images` entry |
| Outputs | 1–5 PNGs per job, same shape, up to 3840 × 2160 |
| Auth | `X-Api-Key` from the [API keys page](https://platform.heygen.com/api-keys); scopes `images:write`, `images:read`, `assets:write` for uploads |

### Create

The call behind the train scene above:

```bash theme={null}
curl -X POST https://api.heygen.com/v3/models/images \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: serena-train-window-001" \
  -d '{
    "model": "heygen-image-1",
    "identity_images": [
      { "type": "asset_id", "asset_id": "'"$IDENTITY_1"'" },
      { "type": "asset_id", "asset_id": "'"$IDENTITY_2"'" },
      { "type": "asset_id", "asset_id": "'"$IDENTITY_3"'" }
    ],
    "reference_images": [{ "type": "asset_id", "asset_id": "'"$TRAIN_WINDOW_REF"'" }],
    "aspect_ratio": "3:4",
    "num_images": 1,
    "seed": 3000
  }'
```

### Retrieve

Poll [`GET /v3/models/images/{generation_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-heygen-image) until the status leaves `pending`. A `completed` job lists exactly `num_images` entries in `images`, in stable order, each with its `image_url`, `width`, `height` and `seed`. A `failed` or `cancelled` job carries `failure_code` and `failure_message` and no partial images. The lookup returns `200` even when the job failed, and there is no callback. Download URLs expire; retrieve the job again for fresh ones, and keep `generation_id` and `image_id` as the stable identifiers.

## Choose your inputs

* **`identity_images`**: one to five photos of the person whose identity should appear in the result. Use clear photos where their face is visible. These are multiple views of one identity, not separate generation requests.
* **`reference_images`**: an array with exactly one image showing the desired clothing, pose, composition, and background. It guides the look of every output in the job.

Each input is an uploaded `asset_id`, an HTTPS `url`, or inline `base64` with a `media_type`, and you can mix them within a request.

Uploaded assets must be images owned by the calling workspace. Use the returned `asset_id` from the [asset upload API](https://heygen-1fa696a7.mintlify.site/reference/upload-asset.md), not a generated output's `image_id`.

URL inputs must be publicly accessible HTTPS URLs pointing directly to an image; redirects are not followed. Image downloads are limited to 16 MiB. Inline base64 inputs are limited to 5 MiB of decoded image data.

## Parameters

The full field list is in [the API reference](https://heygen-1fa696a7.mintlify.site/reference/create-heygen-image.md). `model` accepts only `heygen-image-1`, and `mode` defaults to `identity_remix`. `reference_images` takes exactly one image; an empty array is rejected. `num_images` runs 1 to 5 (default `1`), and `seed` from 0 to 4,294,967,295. Omit `aspect_ratio` or send `null` to match the reference image after EXIF orientation. Unknown fields are rejected, including `prompt`, a singular `reference_image`, custom dimensions and callback fields.

## Output

Use `aspect_ratio` to choose the output shape, or omit it to follow the reference image. Identity images do not determine output shape. When inferring from the reference, its width-to-height ratio must be between 1:4 and 4:1.

The model chooses its native canvas using its 4K training policy and then center-crops a narrow border to deliver the requested ratio. There is no output upscaling. Explicit presets have exact ratios; inferred ratios round to the nearest pixel. Returned dimensions do not have to be multiples of 32.

| `aspect_ratio` | Delivered width × height |
| - | - |
| `1:1` | 2176 × 2176 |
| `2:3` | 2176 × 3264 |
| `3:2` | 3264 × 2176 |
| `3:4` | 2160 × 2880 |
| `4:3` | 2880 × 2160 |
| `4:5` | 2176 × 2720 |
| `5:4` | 2720 × 2176 |
| `9:16` | 2160 × 3840 |
| `16:9` | 3840 × 2160 |

Always read `width` and `height` from each output. An aspect override changes the generation canvas and may change composition; it is not just a crop of the reference photo. All images in one job share the chosen output shape.

## Retries and seeds

Use a unique `Idempotency-Key` for each new job, and reuse that key with the same body when retrying a submission after a timeout. While the idempotency record is retained, the retry resumes or returns the original job. Use a new key when you want a new generation, even if the inputs are the same. The header is optional, but omitting it allows retries to create additional jobs.

`seed` controls the first output. Later outputs use `seed + 1`, `seed + 2`, and so on. With `seed: 42` and `num_images: 2`, the outputs report seeds `42` and `43`. Each output reports its actual seed; later seeds can exceed the request field's maximum. Different seeds provide variation, but do not guarantee visibly different images. A seed is not an idempotency key or a guarantee of identical results across model updates.

## Errors

Request errors use the standard [HeyGen error format](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md). An invalid field or unsupported image count returns HTTP 400. A generation that is missing or belongs to another workspace returns HTTP 404. API keys must be paid keys with the scopes listed above. Insufficient API credits return HTTP 402 (`insufficient_credit`). A temporary billing or service failure can return HTTP 503; retry with the same idempotency key.

The default rate limits are 30 creation requests per minute and 300 retrieval requests per minute. Workspace limits can differ. If a request returns HTTP 429, follow `Retry-After`.

A generation failure is different from an HTTP request error. A successful status lookup returns HTTP 200 with a terminal status and these fields:

| `failure_code` | Action |
| - | - |
| `no_face_detected` | Replace the image named in `failure_message` with a clear face photo. |
| `multiple_faces_detected` | Replace the image named in `failure_message` with a photo of one person. |
| `generation_failed` | Read `failure_message`. If the failure persists, contact support with the generation ID. |
| `generation_cancelled` | The job was cancelled. Submit a new job if needed. |

Jobs run to completion once submitted; there is no API endpoint for cancelling one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.