gpt-image-2

• Async processing — POST returns a task_id, poll GET /api/v1/tasks/{id} for the result.
• OpenAI-compatible /api/v1/images/generations envelope (text-to-image / image-to-image).
• 14 ratios via size; three resolution tiers (1k / 2k / 4k) via resolution.
• Up to 16 reference images via image_urls — public HTTP(S) URLs only.
• Single image per request — n is fixed at 1.
• Flat per-resolution price; failed / moderated requests are not charged.

Try it

POST /api/v1/images/generations
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "model": "gpt-image-2",
  "prompt": "a cute red panda eating bamboo",
  "size": "1:1"
}

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",
    "prompt": "a ginger cat on a windowsill at sunset, watercolor",
    "size": "16:9",
    "resolution": "2k"
  }'

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",
        "prompt": "a ginger cat on a windowsill at sunset, watercolor",
        "size": "16:9",
        "resolution": "2k",
    },
    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",
    prompt: "a ginger cat on a windowsill at sunset, watercolor",
    size: "16:9",
    resolution: "2k",
  }),
});
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",
        "prompt":     "a ginger cat on a windowsill at sunset, watercolor",
        "size":       "16:9",
        "resolution": "2k",
    })
    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",
  "status": "processing",
  "created_at": 1735000000
}

Hold onto id and poll GET /api/v1/tasks/{id} until completion.

Endpoint

POST /api/v1/images/generations    # submit a job
GET  /api/v1/tasks/{id}            # poll for the result

Async — submit returns a task_id immediately; the actual image arrives via the polling endpoint. Polling is free.

Authentication

Bearer token, minted at reapi.ai/settings/apikeys.

Authorization: Bearer rk_live_xxx

Body

model

string · required · default "gpt-image-2"

Must be "gpt-image-2".

prompt

string · required

1 – 4000 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 in the prompt confuses the upstream.

size

string · default "1:1" (text-to-image) / inherited (image-to-image)

Output ratio. One of these 14 values:

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

auto lets the upstream pick from the prompt or first reference image. Pixel strings (e.g. 1024x1024) are not accepted — combine size with resolution to control output pixels. Anything outside the list is rejected with 400.

When image_urls is provided without size, the output inherits the first reference image's resolution (image-to-image mode). Pass size to force a specific ratio.

resolution

string · default "1k"

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

4k is only valid with the six widescreen sizes below. Other sizes — including auto — exceed the model's total-pixel cap and are rejected with 400.

n

integer · default 1 · must be 1

Single image per request. This variant produces one image per call; sending any other value returns 400. For batches up to 4, use gpt-image-2 stable.

image_urls

string[] · optional

Reference images for image-to-image. Up to 16 entries. Each entry must be a public HTTP(S) URL — data: / base64 payloads are rejected. Upload to your own object storage (S3 / R2 / OSS) and pass the URL.

Use cases

1. Text-to-image (minimal)

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a ginger cat on a windowsill at sunset, watercolor"
  }'

2. Text-to-image at 2K widescreen

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "size": "16:9",
    "resolution": "2k"
  }'

3. Text-to-image at 4K

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "ancient castle beneath a starry sky",
    "size": "16:9",
    "resolution": "4k"
  }'

4. Image-to-image (single reference)

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "turn this photo into a watercolor painting",
    "image_urls": ["https://your-cdn.com/photo.jpg"]
  }'

5. Multi-reference fusion

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "blend these two photos into a poster",
    "size": "4:3",
    "resolution": "2k",
    "image_urls": [
      "https://your-cdn.com/photo-a.jpg",
      "https://your-cdn.com/photo-b.jpg"
    ]
  }'

6. Force a ratio for image-to-image

When the reference is portrait but you need a landscape output:

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "extend the scene horizontally into a moonlit forest",
    "size": "21:9",
    "resolution": "2k",
    "image_urls": ["https://your-cdn.com/portrait.jpg"]
  }'

Response

POST returns immediately with status: "processing"; poll GET /api/v1/tasks/{id} until status is completed or failed. Both responses share the same envelope — the output field is null until the task finishes.

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

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

{
  "error": {
    "code": 20003,
    "message": "gpt-image-2: field 'quality' is only supported on gpt-image-2-official",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 10003,
    "message": "API key invalid",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 30001,
    "message": "Insufficient credits",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 50001,
    "message": "Rate limit exceeded",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 60099,
    "message": "Internal error — please retry",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

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 error codes (returned via GET /api/v1/tasks/{id} as error.code):

See Errors catalog for the full code list.

Polling

Recommended cadence:

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

A 1K image typically completes in 30–60s; 2K adds ~30s; 4K can take 90–120s.

Differences from the stable channel

Related

• gpt-image-2 stable — full feature surface (batch, mask, quality tiers).
• Errors catalog
• Authentication
• Quickstart
• Pricing — gpt-image-2