# GPT Image 2 API parameters: size, resolution, aspect ratio and quality

By SeedRouter · Published 2026-09-23 · Updated 2026-09-23

The GPT Image 2 API takes the model name in `model`, the output dimensions in `size` as `WIDTHxHEIGHT` pixels, and the quality in `quality` (`low`, `medium`, `high` or `auto`). There is no `resolution` or `aspect_ratio` field. To get a 16:9 image at 4K you send `"size": "3840x2160"`. Sizes must use multiples of 16, keep both edges at or under 3840 pixels, stay between 1:3 and 3:1, and fall between 655,360 and 8,294,400 pixels.

This guide covers each parameter that changes the picture, with the exact value to send and the error a wrong value returns. Every error below was checked against the live API.

## What is the GPT Image 2 model name in the API?

Use `gpt-image-2` or `gpt-image-2-official`. Both are the same model with the same fields; `gpt-image-2` charges one flat price per delivered image, and `gpt-image-2-official` bills the tokens each render reports.

Names from headlines do not work as model IDs. `gpt-image-2.0`, `GPT Image 2` or `chatgpt-images-2` all return HTTP 400 with error code `20002`.

## How do you set the resolution and aspect ratio?

With `size`, in pixels. Pick the aspect ratio and the pixel budget you want, then send the resulting width and height:

| Aspect ratio | About 1K    | About 2K    | 4K          |
| ------------ | ----------- | ----------- | ----------- |
| 1:1          | `1024x1024` | `2048x2048` | `2880x2880` |
| 3:2          | `1248x832`  | `2496x1664` | `3504x2336` |
| 2:3          | `832x1248`  | `1664x2496` | `2336x3504` |
| 4:3          | `1152x864`  | `2304x1728` | `3264x2448` |
| 3:4          | `864x1152`  | `1728x2304` | `2448x3264` |
| 16:9         | `1280x720`  | `2560x1440` | `3840x2160` |
| 9:16         | `720x1280`  | `1440x2560` | `2160x3840` |
| 21:9         | `1456x624`  | `3024x1296` | `3808x1632` |
| 3:1          | `1728x576`  | `3504x1168` | `3840x1280` |

These are the same conversions the [Playground](https://seedrouter.ai/models/gpt-image-2#playground) uses when you choose a ratio and a 1K, 2K or 4K preset. Square 4K stops at `2880x2880` because a 3840-pixel square would exceed the total pixel limit.

`size: "auto"` leaves the dimensions to the model. It is the default, and convenient, but set an explicit size when outputs need to match a layout or each other.

OpenAI describes output above 2560×1440 as experimental. It is accepted within the limits here, but a larger canvas is not a promise of more detail.

## Which size values are rejected?

| Value sent               | Why it fails         | Response                          |
| ------------------------ | -------------------- | --------------------------------- |
| `"size": "16:9"`         | Ratios are not sizes | 400 `20001`, message names `size` |
| `"size": "4096x2304"`    | Edge above 3840      | 400 `20001`, message names `size` |
| `"size": "1000x1000"`    | Not a multiple of 16 | 400 `20001`, message names `size` |
| `"size": "3840x1024"`    | Wider than 3:1       | 400 `20001`, message names `size` |
| `"resolution": "4k"`     | Unknown field        | 400 `20001`, no field named       |
| `"aspect_ratio": "16:9"` | Unknown field        | 400 `20001`, no field named       |

Note the last two rows. An unknown field is rejected, but the error does not name it. If you get `20001` with the general message "Check the parameters against the API documentation", look for a field the API does not accept, such as `resolution`, `aspect_ratio` or `response_format`.

## Which quality should you choose?

`quality` accepts `low`, `medium`, `high` and `auto`. Higher steps take longer and hold finer detail. `xhigh` and `max` belong to GPT Image 2.5 only; sending them to GPT Image 2 returns `20001` with a message that names `quality`.

A practical routine: draft at `low` while the composition is still changing, check texture and small text at `medium`, and produce finals at `high`. On `gpt-image-2` the price is the same at every step. On `gpt-image-2-official` higher steps report more output tokens, so they cost more. The [pricing guide](https://seedrouter.ai/blog/gpt-image-2-pricing) shows the numbers.

`auto` lets the model choose the step. Set an explicit value when you compare runs, or two "identical" requests may render at different steps.

## What controls format and background?

* `output_format`: `png` (default) or `jpeg`. WebP output is not offered; `webp` returns `20001` with a message that names `output_format`.
* `output_compression`: 0 to 100, only with `jpeg`.
* `background`: `auto`, `opaque` or `transparent`. Transparency needs `png`; `transparent` with `jpeg` returns `20001` with a message that names `background`.
* `n`: 1 to 10 images per request. You are billed for the images delivered.
* `moderation`: `auto` or `low`.

## How are reference images and masks passed?

As URLs, never as files or base64. `images` takes 1 to 16 objects shaped `{"image_url": "https://..."}`, and sending it turns the request into an edit. `mask` takes one object of the same shape: a PNG the size of the first reference image, where the transparent area marks what to change. The [reference](https://seedrouter.ai/docs/gpt-image-2) lists the file limits.

## Frequently asked questions

### Does GPT Image 2 support 4K?

Yes, within the limits above. `3840x2160` for 16:9 and `2160x3840` for 9:16 are the largest frames, and `2880x2880` is the largest square.

### Can I send an aspect ratio instead of pixels?

Not to the API. Convert the ratio to a `WIDTHxHEIGHT` size first, using the table above or the Playground, which shows the exact size before it submits.

### What is the default size and quality?

Both default to `auto`, which leaves the choice to the model. Send explicit values when you need predictable output.

## Send pixels, set the quality, read the error message

Almost every parameter problem is one of three things: a ratio sent as a size, a field the API does not accept, or a value outside the limits. The error message names the field for the first and third; a general message that names no field points at the second. Keep this page next to the [GPT Image 2 API reference](https://seedrouter.ai/docs/gpt-image-2) while you integrate.