> ## 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
> Generate identity-focused portraits from photos of a person and a reference look. One to five images per job, at $0.28 per image.
HeyGen Image 1 generates portraits that preserve a person's identity while following the clothing, pose, composition, and background of a reference image. Provide photos of the person and a separate image showing the look you want. The person in the reference image can be someone else.
This is an identity-focused portrait model. The current API requires both image inputs and does not accept a custom text prompt.
The only supported mode is `identity_remix`. It uses identity photos and one appearance reference to generate portraits. Omit `mode` to use `identity_remix`. An unknown value or `null` returns HTTP 400.
| Mode | You give it | You get |
| - | - | - |
| `identity_remix` | One to five identity images and exactly one reference image | One to five portraits that preserve the identity and follow the reference look |
## Build with it
| | |
| - | - |
| Model identifier | `heygen-image-1` |
| Create | [`POST /v3/models/images`](/reference/create-heygen-image) |
| Retrieve | [`GET /v3/models/images/{generation_id}`](/reference/get-heygen-image) |
| Auth | `x-api-key` header, from [your API settings](https://app.heygen.com/developers/api) |
| Scopes | `images:write` to create; `images:read` to retrieve; `assets:write` if uploading inputs |
| Outputs per job | 1–5 images |
| Output format and size | PNG; resolution follows the aspect ratio and model canvas policy |
| API price | \$0.28 per generated image; see [pricing](#pricing) |
### Generate images
The following request generates two images from the same identity and reference look:
```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: portrait-job-001" \
-d '{
"model": "heygen-image-1",
"mode": "identity_remix",
"identity_images": [
{ "type": "asset_id", "asset_id": "IDENTITY_ASSET_ID" }
],
"reference_images": [
{ "type": "asset_id", "asset_id": "REFERENCE_ASSET_ID" }
],
"aspect_ratio": "3:4",
"num_images": 2,
"seed": 42
}'
```
A successful submission returns **HTTP 202**:
```json theme={null}
{
"data": {
"generation_id": "GENERATION_ID",
"status": "pending"
}
}
```
Save `generation_id` and use it to poll. Acceptance means the job has been submitted; generation can still fail later.
### Retrieve the result
```bash theme={null}
curl https://api.heygen.com/v3/models/images/GENERATION_ID \
-H "x-api-key: $HEYGEN_API_KEY"
```
The response is **HTTP 200**, including when the job has failed. Inspect `data.status`:
| Status | Meaning | `images` |
| - | - | - |
| `pending` | Waiting or generating. Continue polling. | `[]` |
| `completed` | All requested images are available. | Exactly `num_images` entries |
| `failed` | Generation failed. Read `failure_code` and `failure_message`. | `[]` |
| `cancelled` | Generation was cancelled. Read `failure_code` and `failure_message`. | `[]` |
Poll every few seconds, backing off on rate limits or temporary errors, until a terminal status is returned. There is no separate `processing` status and no partial-result response.
Example completed job:
```json theme={null}
{
"data": {
"generation_id": "GENERATION_ID",
"status": "completed",
"model": "heygen-image-1",
"num_images": 2,
"created_at": 1790337600,
"images": [
{
"image_id": "IMAGE_ID_1",
"image_url": "https://example.com/signed-image-1.png",
"width": 2160,
"height": 2880,
"seed": 42
},
{
"image_id": "IMAGE_ID_2",
"image_url": "https://example.com/signed-image-2.png",
"width": 2160,
"height": 2880,
"seed": 43
}
]
}
}
```
`images` is always an array, including when requesting one image. Its order and output IDs remain stable across polls. `generation_id` identifies the whole job; each `image_id` identifies one generated output. Poll using the generation ID, not an image ID.
`created_at` is the job's creation time in Unix seconds. Download URLs expire; retrieve the job again to obtain usable URLs. Store generation and image IDs for tracking rather than treating a signed URL as a permanent identifier.
## Pricing
**The standard API price is \$0.28 per generated image.** The same rate applies to every supported aspect ratio and to jobs with one to five images. There is no batch discount.
The base price for a job is `num_images × $0.28`:
| `num_images` | Base price (USD) |
| - | - |
| 1 | \$0.28 |
| 2 | \$0.56 |
| 3 | \$0.84 |
| 4 | \$1.12 |
| 5 | \$1.40 |
These are base prices before API-credit rounding. The total credit deduction is rounded up once per request, after multiplying by the number of images. Contract pricing, if applicable, follows your account's rate card.
Your API balance must cover the whole job. If a charged job fails or is cancelled, its charge is refunded. Reusing an idempotency key for the same job does not create another charge. Check your balance and charges on the [API usage page](https://app.heygen.com/developers/usage).
## 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 uses the same asset format as other HeyGen APIs. You can mix input types within a request.
```json Uploaded asset theme={null}
{ "type": "asset_id", "asset_id": "ASSET_ID" }
```
```json HTTPS URL theme={null}
{ "type": "url", "url": "https://example.com/photo.jpg" }
```
```json Inline base64 theme={null}
{ "type": "base64", "media_type": "image/jpeg", "data": "BASE64_ENCODED_IMAGE" }
```
Uploaded assets must be images owned by the calling workspace. Use the returned `asset_id` from the [asset upload API](/reference/upload-asset), 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
| Field | Required | Description |
| - | - | - |
| `model` | Yes | Only `heygen-image-1`. Release IDs and internal model names are not accepted. |
| `mode` | No | Only `identity_remix`. Defaults to `identity_remix` when omitted. |
| `identity_images` | Yes | Array of 1–5 image assets for the identity to preserve. |
| `reference_images` | Yes | Array of exactly one image asset showing the desired look. Empty arrays and arrays with more than one image are rejected. |
| `aspect_ratio` | No | One of `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, or `16:9`. Omit or use `null` to match the reference image after EXIF orientation. |
| `num_images` | No | Integer from 1 to 5. Defaults to `1`. |
| `seed` | No | Integer from 0 to 4,294,967,295 for the first output. Chosen randomly when omitted or `null`. |
Unknown fields are rejected. `prompt`, the singular `reference_image` field, custom dimensions, and callback fields are not supported.
## 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. The example above returns 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](/docs/error-codes). 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 need the scopes listed above, and trial API keys are not supported. 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. |
Failed and cancelled jobs return no partial images. There is no API endpoint for cancelling a job.
## Specs at a glance
| | |
| - | - |
| Model | `heygen-image-1` |
| Mode | `identity_remix` |
| Identity inputs | 1–5 images of one person |
| Appearance reference | Exactly one image in `reference_images` |
| Outputs | 1–5 PNG images per job |
| Shape | Nine aspect-ratio presets, or inferred from the reference image |
| API price | \$0.28 per image before API-credit rounding |
| Custom prompt | Not supported |
| Completion | Poll by `generation_id`; no callbacks or partial results |
| API keys | Paid API keys |
Create a key and check your usage.
Upload identity and reference photos, then use their asset IDs in a request.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.