GPT Image 2 · API

Quick start

Three steps: submit a job, poll it, take the image link. Replace YOUR_API_KEY with your key and the commands below run as they are.

Step 1 · Submit (returns a job id at once, HTTP 202)

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "A cafe menu poster titled Autumn Specials listing three drinks with prices, clean layout", "size": "16:9", "resolution": "2K"}'

Response (HTTP 202)

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "gpt-image-2"
}

Step 2 · Poll every 2–3 seconds until status is succeeded or failed

curl https://nezhagate.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

Response when it succeeds

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "gpt-image-2",
  "data": [
    {"url": "https://img.nezhagate.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2"}
}

Step 3 · data[0].url is the image (PNG). It is kept for 15 days; download it to your own storage to keep it longer.

Complete example (Python: submit, wait, save to disk)

import time
import requests

BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. submit
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "gpt-image-2",
    "prompt": "A cafe menu poster titled Autumn Specials listing three drinks with prices, clean layout",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. poll every 3 seconds until it finishes
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. download the image
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("gpt-image-2.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

Authentication

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create an API Key in the console to start.

Request parameters

The JSON body of POST /v1/images/generations:

Other OpenAI parameters (background, output_format, response_format, style and the like) do not change the price and are not guaranteed to take effect; results are always PNG, returned as a url.

Price

Billed per image by tier only: aspect ratio, text-to-image or image-to-image make no difference. The tier price is held when you submit and refunded in full if the job fails. 1 credit = $0.005.

Aspect ratio, resolution and output size

Put the ratio in size and the tier in resolution. The image is delivered at exactly the size in the table: the tier sets the longest side and the other side follows the ratio. Ratios not in the table work the same way.

• At 1K the model composes the picture at the closest landscape, portrait or square shape, and the gateway then centre-crops and resizes it to the size in the table; the further a ratio is from 3:2, 2:3 or 1:1, the more of the edges is cut. The gateway adds a sentence about the ratio (in English) to your prompt so the subject stays whole and centred; keep anything that must survive away from the edges.
• The tiers that are drawn natively (see Quality and native resolution below) are drawn at your ratio, so nothing is cropped from the edges.
• size can also be a pixel size (e.g. 1536x1024): the image is delivered at exactly that size (scaled down if the longest side is over 4096). The tier then comes from resolution, or without it from the longest side: up to 1536 is 1K, up to 2048 is 2K, larger is 4K. resolution can raise the tier but never lower it, and it does not change the delivered size, so do not pair a small size with a high tier.

Quality and native resolution

• Without quality the image is drawn at OpenAI's medium detail level. At 1K you can choose low, medium or high, for text-to-image and image-to-image alike; 2K and 4K are always drawn at medium. Any other value (auto, xhigh, max and so on) counts as medium and never causes an error. The price depends only on the resolution tier, never on quality.
• If quality holds 1K, 2K or 4K and resolution is not given, it is read as the resolution tier (size and price follow that tier).
• 1K is drawn at the model's native frame of about 1.57 megapixels (1254×1254 for a square), and the gateway resizes it to the size in the table above.
• 2K and 4K are drawn natively at the ratio you ask for, up to 3840 px on a side and about 8.3 megapixels: 2K 1:1 comes back as 2048×2048, 4K 16:9 as 3840×2160 and 4K 1:1 as 2880×2880. Where the 4K size in the table is larger, the gateway scales the picture up to it (about 7% on each side for 16:9, more for squarer ratios); to receive the native pixels as they are, send a pixel size within those limits, such as 3840x2160.
• Tiers that are drawn natively only run on their native lines: when those are busy the job waits in the queue, and if it still cannot be drawn it fails with a full refund — it is never replaced by an enlarged 1K image.
• A 1K job is occasionally finished on a backup line, where quality may not take effect.

Image-to-image and reference images

• Send image (one picture) or images (several, up to 8; any beyond 8 are not used) and the job runs image-to-image; say in the prompt what to change. POST /v1/images/edits takes the same parameters.
• Both endpoints take a JSON body only, not a multipart file upload, so the OpenAI SDK's images.edit() cannot be used as is: pass links or base64 as in the example below.
• Each reference can be a public image URL (http or https), a data: URI or plain base64, up to 16MB each, in a common format such as JPEG, PNG or WebP.
• A URL has to download the image itself: not a web page, and not behind a login or hotlink protection. A reference we cannot read is refused at submit with a 400 that says which one and why; no job is created and nothing is charged.
• The output ratio comes from size, not from the reference. To keep the original ratio, set size to it.
• We host the references for you and keep them for 7 days.

Image-to-image with two references

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

Job status and fields

GET /v1/images/jobs/{id} reports these statuses; every field is described in Async jobs. Poll every 2–3 seconds, or use a webhook.

One account runs up to 50 jobs at a time; further jobs wait in submission order, and a job that has not started after 15 minutes fails and is refunded in full. Job records are kept for 3 days and image links for 15 days.

How long it takes

From submit to result, 1K usually takes 20–60 seconds; 2K and 4K are drawn natively and usually take 30–120 seconds. Image-to-image and several references take longer, and a job the gateway retries on another line can take a few minutes.

Real calls over the last 7 days: median 25 s, 90% done within 42 s.

Errors and refunds

An error at submit comes back at once as HTTP 4xx / 5xx: no job is created and nothing is charged. A failure after the job was accepted is reported by the job endpoint, and the hold is refunded in full. Every code is listed under Error codes.

Errors at submit

Failed jobs (status failed)

Webhooks instead of polling

Add callback_url when you submit and the moment the job ends, success or failure, the gateway pushes exactly what the poll endpoint returns to that URL, signed and retried on failure. You can also set an account-wide address under Settings → Webhook in the console. Webhook docs →

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "A cafe menu poster titled Autumn Specials listing three drinks with prices, clean layout", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'