IMAGE API

GPT Image 2 · Image edits

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

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": "Keep the subject and replace the background with a quiet garden",
    "images": [
      "https://example.com/reference.png"
    ]
  }
}'

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": "Keep the subject and replace the background with a quiet garden",
    "images": [
      "https://example.com/reference.png"
    ],
    "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\":\"Keep the subject and replace the background with a quiet garden\",\"images\":[\"https://example.com/reference.png\"],\"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`

Replace https://example.com/reference.png with a publicly reachable reference-image URL. This is the platform images array, not the official multipart image field.

Request example

The platform origin is filled in at build time. Set API_KEY to your server-side key before running.

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": "Keep the subject and replace the background with a quiet garden",
    "images": [
      "https://example.com/reference.png"
    ]
  }
}'

Retrieve the result

The creation response accepts a task, not the final output. Replace TASK_ID with its returned ID and poll until succeeded or failed.

curl "https://newrouters.com/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

Read result on success and error on failure. Keep the original task ID when the upstream outcome is unknown; do not submit a duplicate paid generation.

Parameters

Field	Type	Requirement	Default	Constraints
`size`	string	Optional	—	Native size; takes 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	Required for edits	—	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`
`output_format`	enum	Optional	`"jpeg"`	`png`, `jpeg`, `webp`

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.

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 alignment

The corresponding official workflow is POST /v1/images/edits. This page submits the platform asynchronous POST /v1/tasks request. Use fields supported by the platform schema rather than assuming every official field is compatible.

Official image API guide

Official sources and identity

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

Pricing and troubleshooting

Check current availability, contract and account pricing before integration. Keep request IDs and usage receipts when diagnosing errors. Complete API reference