---
title: "Create Image"
method: POST
path: "/v3/images"
tags: ["Images"]
---

# Create Image

`POST /v3/images`

## Request

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

Generate images with `gpt-image-2.5`, `nano-banana-2` or `nano-banana-2.1`, or edit the reference images when any are given. The request waits for the images and answers 200 with them; a generation is capped at 300 seconds. Send an `Idempotency-Key` header with every request: it is required. Repeating a request with the same key and body returns the original result instead of generating again, and a duplicate sent while the original is still running gets 409 `request_in_progress`. A request the workspace's API credits cannot cover at the model's list price is refused with 402 `insufficient_credit` before any work starts. The credits are charged once the images are generated, at what the image model billed for the request when it reports it, otherwise at the list price; a failed generation is not charged. If the balance no longer covers the charge when the images are ready, the request answers 402 `insufficient_credit` without them. The request body is capped at about 7.4 MiB, so inline `base64` references together must stay under about 5 MiB decoded; send larger or additional images as `url` or `asset_id`.

## Headers

- `Idempotency-Key` string, required

## Request body

- union
  - GptImage25Request: GPT Image 2.5.
    - `model` 'gpt-image-2.5', required
    - `prompt` string, required: What to generate, or how to edit the reference images.
    - `num_images` integer: Number of images to generate, from 1 to 4.
    - `aspect_ratio` '1:1' | '16:9' | '9:16' | '4:3' | '3:4', nullable: Output aspect ratio. 16:9 when omitted.
    - `reference_images` union[]: Reference images. When non-empty the request is an edit.
      - 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
  - NanoBanana2Request: Nano Banana 2 (Gemini 3.1 Flash Image).
    - `model` 'nano-banana-2', required
    - `prompt` string, required: What to generate, or how to edit the reference images.
    - `num_images` integer: Number of images to generate, from 1 to 4.
    - `aspect_ratio` '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3' | '21:9', nullable: Output aspect ratio. 16:9 when omitted.
    - `reference_images` union[]: Reference images. When non-empty the request is an edit.
      - 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
  - NanoBanana21Request: Nano Banana 2.1.
    - `model` 'nano-banana-2.1', required
    - `prompt` string, required: What to generate, or how to edit the reference images.
    - `num_images` integer: Number of images to generate, from 1 to 4.
    - `aspect_ratio` '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3' | '21:9', nullable: Output aspect ratio. 16:9 when omitted.
    - `reference_images` union[]: Reference images. When non-empty the request is an edit.
      - 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

## Response `200`

The finished generation with its images.

- object
  - `data` ThirdPartyImageResponse
    - `id` string, required: Generation identifier, for reading the generation again.
    - `status` 'pending' | 'completed' | 'failed', required: `completed` with its images, `failed` with a failure code, or `pending` while the creating request is still running.
    - `model` string, required
    - `created_at` integer, required: Request creation time as Unix seconds.
    - `images` ThirdPartyGeneratedImage[], required: Generated images in output order; empty unless completed.
      - `url` string, required: Download URL. It expires; read the generation again for a fresh one.
      - `width` integer, required
      - `height` integer, required
    - `failure_code` 'content_policy_violation' | 'partial_generation' | 'vendor_unavailable' | 'ai_vendor_access_restricted' | 'insufficient_credit' | 'api_key_required' | 'internal_error'
    - `failure_message` string, nullable

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `402`: Insufficient credit
- `403`: Forbidden — `error.code` is one of: `resource_access_denied`, `ai_vendor_access_restricted`.
- `409`: Conflict — `error.code` is one of: `request_in_progress`, `conflict`.
- `429`: Rate limit exceeded
- `503`: Temporarily unavailable — the request did not complete and is safe to retry.

## Changes

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

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/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)