GPT Image 2 API parameters: size, resolution, aspect ratio and quality
The GPT Image 2 API parameters that shape the image: model name, size and resolution, aspect ratios, 4K limits, quality, formats and the errors they return.
Read as MarkdownThe 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 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 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) orjpeg. WebP output is not offered;webpreturns20001with a message that namesoutput_format.output_compression: 0 to 100, only withjpeg.background:auto,opaqueortransparent. Transparency needspng;transparentwithjpegreturns20001with a message that namesbackground.n: 1 to 10 images per request. You are billed for the images delivered.moderation:autoorlow.
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 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 while you integrate.
