gpt-image-2-official

Quick example

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-official",
    "prompt": "ancient castle beneath a starry sky",
    "size": "16:9",
    "resolution": "2k",
    "quality": "high",
    "n": 1
  }'

import requests

resp = requests.post(
    "https://reapi.ai/api/v1/images/generations",
    headers={
        "Authorization": "Bearer rk_live_xxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2-official",
        "prompt": "ancient castle beneath a starry sky",
        "size": "16:9",
        "resolution": "2k",
        "quality": "high",
        "n": 1,
    },
    timeout=30,
)
print(resp.json())

const r = await fetch("https://reapi.ai/api/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer rk_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2-official",
    prompt: "ancient castle beneath a starry sky",
    size: "16:9",
    resolution: "2k",
    quality: "high",
    n: 1,
  }),
});
console.log(await r.json());

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "model":      "gpt-image-2-official",
        "prompt":     "ancient castle beneath a starry sky",
        "size":       "16:9",
        "resolution": "2k",
        "quality":    "high",
        "n":          1,
    })
    req, _ := http.NewRequest("POST",
        "https://reapi.ai/api/v1/images/generations", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer rk_live_xxx")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    out, _ := io.ReadAll(resp.Body)
    fmt.Println(string(out))
}

Submit response

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "gpt-image-2-official",
  "status": "processing",
  "created_at": 1735000000
}

Poll GET /api/v1/tasks/{id} (see the Tasks reference) until status === "completed". The completed payload's output.image_urls holds the generated image URLs (length = n), valid for 7 days.

Authentication

Every call needs a Bearer token. Generate keys at reapi.ai/settings/apikeys.

Authorization: Bearer YOUR_API_KEY

Keys carry the active workspace's billing scope — there is no separate project header.

Endpoint

POST /api/v1/images/generations
GET  /api/v1/tasks/{id}

Submission is async. The POST returns immediately with a task_id; the task endpoint returns the same envelope until completion. Polling does not consume credits.

Request body

model — required

string. Must be "gpt-image-2-official".

prompt — required

string, 1–32,000 characters. English and Chinese both supported. Detailed prompts produce better results. Every prompt goes through pre-submission moderation; rejected prompts return 400 at no charge.

Don't restate the ratio in the prompt — pass it via size. Repeating it confuses the upstream.

size — string, default "1:1"

Output ratio. One of these 14 values (or auto to let the upstream pick from the prompt / first reference image):

auto
1:1   16:9   9:16   4:3   3:4
3:2   2:3    5:4    4:5
2:1   1:2    21:9   9:21

This channel additionally accepts a pixel string WIDTHxHEIGHT (e.g. 1024x1024, 3840x2160); the upstream snaps it to the closest supported dimension. Anything outside the list and not a pixel string is rejected with 400.

When size is omitted:

• T2I (no image_urls) → defaults to "1:1".
• I2I (image_urls set) → output mirrors the first reference image's ratio (upstream-side derivation; gateway omits the field).

4K constraint

resolution: "4k" is only valid with the six widescreen sizes below. Other ratios — including auto — exceed the model's total-pixel cap and are rejected with 400. size is required when resolution: "4k"; sending 4K with no size is rejected before the request leaves the gateway.

resolution — string, default "1k"

1k / 2k / 4k. Case-insensitive — "2K" and "2k" are equivalent. Drives pricing.

quality — string, default "auto"

auto / low / medium / high. Higher tiers are slower and price separately.

n — integer, default 1

Number of images per request. Range 1–10. Each generated image is billed individually — a 4-image batch costs 4× the per-image rate. output.image_urls length matches n.

image_urls — string[]

Reference images for image-to-image. Up to 16 entries. Triggers I2I when set. Public HTTP(S) URLs only.

mask_url — string

PNG mask URL for inpainting. Requires image_urls with at least one entry. The mask must:

• carry an alpha channel where the model should paint, and
• share dimensions with the first entry in image_urls.

Public HTTP(S) URL only. Mismatched dimensions or a fully opaque mask return 400 from upstream.

Response envelope

Submit and poll share the same shape — only status and output fill in over time.

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "gpt-image-2-official",
  "status": "completed",
  "created_at": 1735000000,
  "output": {
    "image_urls": [
      "https://cdn.reapi.ai/media/tasks/018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e/0.png",
      "https://cdn.reapi.ai/media/tasks/018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e/1.png"
    ]
  },
  "error": null
}

Upstream errors (502 / 503)

reAPI does not surface raw upstream 5xx codes to the caller. When the upstream provider returns 502 Bad Gateway, 503 Service Unavailable, or a connection failure, the worker retries up to 5 attempts with exponential backoff (~30s total budget). If all retries fail, the task ends with one of these reAPI-specific codes (returned via GET /api/v1/tasks/{id} as error.code):

See Errors catalog for the full code list.

Validation errors

All cases below return HTTP 400 with the noted code. Pattern-match on code, not message — message strings carry request-specific context (field names, observed values) and are not a stable contract.

The full envelope is { "error": { "code", "message", "request_id" } } — see Errors catalog for the wire format and request_id correlation.

Recipes

Text-to-image — minimal

{
  "model": "gpt-image-2-official",
  "prompt": "ancient castle beneath a starry sky"
}

2K poster

{
  "model": "gpt-image-2-official",
  "prompt": "cyberpunk night cityscape",
  "size": "16:9",
  "resolution": "2k",
  "quality": "high"
}

4K wallpaper

{
  "model": "gpt-image-2-official",
  "prompt": "panoramic snow-capped mountains at sunrise",
  "size": "16:9",
  "resolution": "4k",
  "quality": "high"
}

Multi-reference fusion (image-to-image)

{
  "model": "gpt-image-2-official",
  "prompt": "blend the two references into one cohesive illustrated poster",
  "size": "1:1",
  "quality": "high",
  "image_urls": [
    "https://your-cdn.com/input-a.png",
    "https://your-cdn.com/input-b.png"
  ]
}

Mask-based inpainting

The mask must match the dimensions of the first image_urls entry and carry an alpha channel where the model should paint.

{
  "model": "gpt-image-2-official",
  "prompt": "replace the background with a desert sunset",
  "size": "1:1",
  "quality": "medium",
  "image_urls": ["https://your-cdn.com/photo.png"],
  "mask_url": "https://your-cdn.com/mask.png"
}

Batch of 4 variations

{
  "model": "gpt-image-2-official",
  "prompt": "four minimalist poster variations of a red fox",
  "size": "1:1",
  "quality": "low",
  "n": 4
}

Polling pattern

Latency depends heavily on quality and resolution:

Recommended cadence:

0–30s:    wait before the first poll
30s–3m:   poll every 3–5s
3m+:      back off to 10s; cap at 30s

Set client-side request timeouts to ≥ 180 seconds when using quality: "high" with 2k / 4k.

The worker's wall-clock cap is 1 hour (image tasks), comfortably above any realistic queue.

Pricing

Per-image rates depend on three axes:

• Resolution (1k / 2k / 4k)
• Quality (low / medium / high — auto bills at high)
• size (the 2k / 4k cells charge slightly more for the widest ratios; live numbers on the model page are authoritative)

When size is "auto", reAPI prices against the most expensive ratio at the resolved (resolution, quality) cell so the bill never undershoots once the upstream picks a ratio at runtime. The forwarded body keeps auto — the override is billing-only.

Bill formula (1 credit = $0.001):

credits = ceil(per_image_usd × n × 1000)

Charged on submit; refunded automatically on failed / provider_submit_failed / provider_polling_timeout. Moderated prompts return 400 before charging — no balance impact.

Tips

• Specify ratio in size, not in the prompt. Repeating "16:9 wide shot" inside the prompt confuses the upstream. Use size for shape and the prompt for content / style.
• Set quality explicitly to save money. auto runs at high — if medium is good enough, send "medium" and pay the medium rate.
• Batches are linear cost. n: 4 is exactly 4× the price of n: 1 at the same parameters — no batch discount, but no batch surcharge either.
• Mask alpha matters. The mask's transparent regions are where the model paints; opaque regions are preserved. A fully opaque mask returns 400 from upstream.
• Pre-cache reference images. The upstream fetches each image_urls entry once per submit; if your CDN is slow, latency shows up as polling time, not as billing.

Differences from gpt-image-2

Related

• gpt-image-2 — cheaper variant, single image, flat per-resolution pricing
• Errors catalog
• Authentication
• Quickstart
• Pricing — gpt-image-2