---
title: "Create HeyGen Image"
method: POST
path: "/v3/models/images"
tags: ["Models"]
---

# Create HeyGen Image

`POST /v3/models/images`

## Request

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

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.

## Headers

- `Idempotency-Key` string

## Request body

- CreateImageGenerationRequest
  - `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.
  - `identity_images` union[], required: One to five images of the identity to preserve.
    - union
      - AssetUrl: Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required: Input type discriminator
        - `url` string, required: Publicly accessible HTTPS URL for the asset
      - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required: Input type discriminator
        - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
      - AssetBase64: Asset input via base64-encoded content.
        - `type` 'base64', required: Input type discriminator
        - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
        - `data` string, required: Base64-encoded file content
  - `reference_images` union[], required: Supply exactly one image whose clothing, pose, composition, and background should guide the result.
    - union
      - AssetUrl: Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required: Input type discriminator
        - `url` string, required: Publicly accessible HTTPS URL for the asset
      - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required: Input type discriminator
        - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
      - AssetBase64: Asset input via base64-encoded content.
        - `type` 'base64', required: Input type discriminator
        - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
        - `data` string, required: Base64-encoded file content
  - `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_images` integer: Number of images to generate in this job. Supports one to five.
  - `seed` integer, nullable: Seed for the first image. Each subsequent image increments the seed by one. A random seed is chosen when omitted.

## Response `202`

Accepted — submission acknowledged; poll for completion.

- object
  - `data` CreateImageGenerationResponse
    - `generation_id` string, required: Generation job identifier to use when polling for results.
    - `status` 'pending': The request has been accepted for processing.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `404`: Resource not found
- `409`: A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/models/images/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)