IMAGE API

GPT Image 2 · API guide

Integrate gpt-image-2 through the media task API. Request examples, parameters, authentication and result handling.

POST/v1/tasksMODELgpt-image-2

Official reference gpt-image-2Checked 2026-09-27Official docs

Code examples & responses

Request & responseExamples

POST/v1/tasks

Server-side request

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"
  }
}'

Server-side request

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);

Server-side request

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))

The API origin is filled in. Set API_KEY before running. Examples never submit automatically.

ResponseSelected fields · illustrative values

202Task accepted

JSON

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

200Successful result

JSON

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

Retrieve results after submission

Request lifecycleAsynchronous media

Create a task01
POST /v1/tasks
Submit model + input. Save the returned task id.
202 · pending
Poll status02
GET /v1/tasks/{id}
Wait and poll again while pending or processing.
Wait → poll again
Read the outcome03
result.assets[] / error
Read the result for the terminal task state.
succeeded→ assetsfailed→ error

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	`POST /v1/images/generations`	`POST /v1/tasks` · `input.prompt`
Image to image	`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.
`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.

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 · GPT Image 2 rules

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.

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

Official sources and identity

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