# GPT Image 2 · API guide

Use the exact API model ID `gpt-image-2`. This guide describes the platform contract; check the live catalog before calling the model.

OpenAI separates text-to-image generations from edits with reference images. The platform task API uses the same endpoint for both; the input distinguishes the two workflows.

| Guide | Official Image API | Platform API |
| --- | --- | --- |
| [Text to image](/docs/models/gpt-image-2/generations) | `POST /v1/images/generations` | `POST /v1/tasks` · `input.prompt` |
| [Image to image](/docs/models/gpt-image-2/edits) | `POST /v1/images/edits` | `POST /v1/tasks` · `input.prompt` + `input.images` |

## Choose a workflow

Open the generations or edits guide above for a complete request and result flow. The official endpoint names describe the workflow, not the platform task envelope.

## Model parameters

| Field | Type | Requirement | Default | Constraints |
| --- | --- | --- | --- | --- |
| `size` | string | Optional | — | Native dimensions, taking precedence over resolution and aspect_ratio; `auto` or `WIDTHxHEIGHT`. Multiples of 16; edge ≤ 3840; ratio ≤ 3; 655,360–8,294,400 pixels. See [size rules](#size-constraints). |
| `images` | array | Optional | — | max items 20 |
| `prompt` | string | Required | — | max length 100000 |
| `quality` | enum | Optional | `"medium"` | `low`, `medium`, `high` |
| `background` | enum | Optional | — | `auto`, `transparent`, `opaque` |
| `resolution` | enum | Optional | `"1k"` | `1k`, `2k`, `4k`; Ignored when `size` is supplied |
| `aspect_ratio` | enum | Optional | — | `21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `2:1`, `1:2`, `9:21` |
| `output_format` | enum | Optional | `"jpeg"` | `png`, `jpeg`, `webp` |

Parameters reflect the public contract snapshot. Use GET /v1/media-models for current values and your dashboard for pricing.

<!-- gpt-image-size:start -->
## Size constraints

These native output-size rules apply to GPT Image 2, GPT Image 2.5 Sunburst and Flare, for both generations and edits. Use auto or a WIDTHxHEIGHT pixel size.

| Condition | Native limit |
| --- | --- |
| Width and height | Both must be positive multiples of 16 |
| Longest edge | ≤ 3840 px |
| Long edge / short edge | ≤ 3 |
| Total pixels (width × height) | 655,360–8,294,400 |

Every condition must hold. The official guide labels resolutions above 2560x1440 as experimental.

### Size examples

| size | Meets native rules | Explanation |
| --- | --- | --- |
| 1024x1024 | Valid | Common square |
| 1536x864 | Valid | 16:9 landscape |
| 2880x2880 | Valid | Square at the pixel cap |
| 3840x2160 / 2160x3840 | Valid | Landscape / portrait 4K at the pixel cap |
| 1537x864 | Invalid | Width is not a multiple of 16 |
| 512x512 | Invalid | Below the minimum pixel count |
| 3072x768 | Invalid | 4:1 exceeds the 3:1 ratio limit |
| 3840x3840 | Invalid | Exceeds the pixel cap |
| 4096x4096 | Invalid | Exceeds both edge and pixel caps |

[Official size specification](https://developers.openai.com/api/docs/guides/image-generation#size-and-quality-options) · [GPT Image 2 rules](https://developers.openai.com/api/docs/guides/image-generation#earlier-gpt-image-models)

### Platform sizing parameters

When `size` is supplied, `resolution` and `aspect_ratio` are ignored. `size=auto` (including omission of both `size` and `aspect_ratio`) is billed at the 2K tier, even if `resolution=4k` is also supplied; it does not incur 4K pricing or guarantee 4K output. A concrete `WxH` derives its pricing tier from `size`. To select a resolution tier, omit `size` and use `resolution` + `aspect_ratio`.

Native dimension constraints are checked before submission. Each channel model controls auto and arbitrary-size passthrough. By default, dimensions are matched to the nearest size in a table generated from that channel’s supported ratios and 1K/2K/4K tiers; the channel can alternatively receive the ratio and tier from the same table entry. Native size is forwarded only when enabled. Channels that do not accept auto are excluded from initial routing and retries. Requests fail when no compatible channel remains. Conversion affects upstream execution only; customer pricing uses the original request.

resolution is a platform tier, not an exact pixel edge. The shared conversion maps 4k + 1:1 to 2880x2880 and 4k + 16:9 to 3840x2160. Verify returned dimensions. Platform synchronous image endpoints normalize size into existing tiers and the nearest supported ratio; arbitrary exact dimensions are not guaranteed.

| resolution | aspect_ratio | Shared conversion size |
| --- | --- | --- |
| 1k | 1:1 | 1024x1024 |
| 2k | 1:1 | 2048x2048 |
| 4k | 1:1 | 2880x2880 |
| 4k | 16:9 | 3840x2160 |
| 4k | 9:16 | 2160x3840 |

For a 4K square task using the recommended platform parameters, put the following in input; do not also send size.

```json
{
  "resolution": "4k",
  "aspect_ratio": "1:1"
}
```

<!-- gpt-image-size:end -->

<!-- official-reference:start -->
## Official sources and identity

Checked: 2026-09-27 · Platform model: `gpt-image-2` · Official reference: `gpt-image-2`

- [gpt-image-2 official reference](https://developers.openai.com/api/docs/models/gpt-image-2)
- [OpenAI Images API: generations / edits](https://developers.openai.com/api/docs/guides/image-generation)
<!-- official-reference:end -->

## Request examples in other languages

### cURL

```bash
curl "https://newrouters.com/v1/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  --data '{
  "model": "gpt-image-2",
  "input": {
    "quality": "medium",
    "resolution": "1k",
    "output_format": "jpeg",
    "prompt": "A small red house in a quiet garden"
  }
}'
```

### JavaScript

```javascript
const apiBaseUrl = "https://newrouters.com";
const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error("Set API_KEY in your server environment");

const response = await fetch(apiBaseUrl + "/v1/tasks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + apiKey
  },
  body: JSON.stringify({
  "model": "gpt-image-2",
  "input": {
    "quality": "medium",
    "resolution": "2k",
    "output_format": "jpeg",
    "prompt": "A small red house in a quiet garden",
    "size": "auto"
  }
})
});

const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result);
```

### Python

```python
import json
import os
from urllib.request import Request, urlopen

api_base_url = "https://newrouters.com"
api_key = os.environ["API_KEY"]
body = json.loads("{\"model\":\"gpt-image-2\",\"input\":{\"quality\":\"medium\",\"resolution\":\"2k\",\"output_format\":\"jpeg\",\"prompt\":\"A small red house in a quiet garden\",\"size\":\"auto\"}}")

request = Request(
    api_base_url + "/v1/tasks",
    data=json.dumps(body).encode("utf-8"),
    headers={
    "Content-Type": "application/json",
    "Authorization": "Bearer " + api_key
    },
    method="POST",
)
with urlopen(request) as response:
    print(json.load(response))
```

## Response fields (illustrative values)

### HTTP 202

```json
{
  "id": "TASK_ID",
  "status": "pending",
  "model": "gpt-image-2",
  "result": null,
  "error": null
}
```

### HTTP 200

```json
{
  "id": "TASK_ID",
  "status": "succeeded",
  "model": "gpt-image-2",
  "result": {
    "assets": [
      "https://example.com/output.png"
    ]
  },
  "error": null
}
```