---
title: "Edit images with GPT Image 2 from an instruction, by asset id or by uploaded bytes"
method: POST
path: "/v2/images/edit/gpt-image-2"
tags: ["images-edit"]
---

# Edit images with GPT Image 2 from an instruction, by asset id or by uploaded bytes

`POST /v2/images/edit/gpt-image-2`

Edit one or more source images by describing the change in plain language.
Supply the sources either as `image_asset_identifiers` references (images
already stored with Ideogram) or as raw `images` bytes (multipart requests
only) — callers are never required to upload assets first. If both are
supplied, the references win and the bytes are ignored.

By default the request blocks until the edited images are ready and
returns them in `data`. Set `async` to true to return immediately after
the request is accepted, then poll for completion and results with
`GET /v1/generations/{generation_id}` using the returned `generation_id`.

## Request body

- EditImageGptImage2Request — Supply the source images either as `image_asset_identifiers` references or (multipart requests only) as raw `images` bytes. At least one source is required; if both forms are given, the references are used and the bytes are ignored.
  - `prompt` string, required — The edit instruction to apply to the source images.
  - `image_asset_identifiers` AssetIdentifier[] — Existing upload or generated image assets to edit, by reference. Takes priority over `images` if both are supplied.
    - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required
    - `asset_id` string, required
  - `images` string[] — The source images to edit (max 16, max size 25MB per image), as raw bytes; only JPEG, PNG, and WEBP formats are supported. Multipart requests only; ignored if `image_asset_identifiers` is also supplied.
  - `num_images` integer — The number of edited images to generate.
  - `seed` integer — Random seed. Set for reproducible generation.
  - `aspect_ratio` string — The requested output aspect ratio, for example "1:1", "16:9", or "9:16". Ignored when `resolution` is provided. Defaults to "1:1".
  - `resolution` string — Exact output resolution, formatted as "WIDTHxHEIGHT", for example "2048x2048" or "1920x1088". When provided, this takes precedence over `aspect_ratio`. The dimensions must satisfy GPT Image 2 constraints: each side is a multiple of 16, the largest side is at most 3840px, the long:short ratio is at most 3:1, and total pixels are between 655360 and 8294400 inclusive.
  - `async` boolean — When false (the default), the request blocks until the edited images are ready and returns them in `data`. When true, the request returns as soon as it is accepted; poll for completion and results with `GET /v1/generations/{generation_id}` using the returned `generation_id`.

## Response `200`

The edited images (synchronous requests), or an acknowledgement to poll with `GET /v1/generations/{generation_id}` (`async` requests).

- EditImageGptImage2Response — Response returned by `POST /v2/images/edit/gpt-image-2`. Synchronous requests (the default) include the edited images in `data`. Requests with `async` set to true omit `data`; poll for completion and results with `GET /v1/generations/{generation_id}` using the returned `generation_id`. The seed, width, and height report the values the request resolved to when the caller left them unset.
  - `generation_id` string, required — URL-safe base64 ID of the accepted generation. Accepted by the `GET /v1/generations/{generation_id}` polling endpoint.
  - `data` EditImageObject[] — The edited images, in generation order. Present only for synchronous requests (`async` omitted or false).
    - `url` string, uri, nullable — The direct link to the edited image. Empty when the image did not pass safety checks.
    - `prompt` string, required — The edit instruction the image was generated from.
    - `resolution` string, required — The resolution of the edited image, formatted as "WIDTHxHEIGHT".
    - `is_image_safe` boolean, required — Whether the image passed safety checks. If false, `url` is empty.
    - `seed` integer, required — Random seed. Set for reproducible generation.
  - `seed` integer, required — Random seed. Set for reproducible generation.
  - `width` integer, required — The output width in pixels this request resolved to.
  - `height` integer, required — The output height in pixels this request resolved to.

## Other responses

- `400` — Invalid input provided.
- `401` — Unauthorized.
- `402` — Insufficient credits or quota.
- `404` — A referenced source asset was not found.
- `422` — The prompt did not pass safety checks.
- `429` — Too many requests.
- `500` — Internal server error.
- `503` — The endpoint is temporarily unavailable.

---

[API](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideogram/ideogram-openapi-3-0/revisions/c3c4cbf59bf4/schema)