# GPT Image 2.5 API

> Independent third-party image generation and editing API at https://gptimage25api.com. Not affiliated with OpenAI. GPT Image 2.5 is available with Flare and Sunburst variants.

## Documentation
- [API reference](https://gptimage25api.com/gpt-image-2-5-api): Authentication, parameters, generation, polling, examples and errors.
- [Complete integration guide](https://gptimage25api.com/llms-full.txt): Full contract and runnable examples.
- [OpenAPI 3.1](https://gptimage25api.com/openapi.json): Machine-readable API schema.
- [AI integration prompt](https://gptimage25api.com/ai-prompt.txt): Instructions for coding assistants.

## Account
- [Sign in](https://gptimage25api.com/auth/login)
- [Create API keys](https://gptimage25api.com/dashboard/api-keys)
- [Pricing](https://gptimage25api.com/pricing)
- [Playground](https://gptimage25api.com/dashboard/home)

## API essentials
Base URL: https://gptimage25api.com
Generate: POST /api/v1/images/generate
Status: GET /api/v1/images/status?task_id=<id>
Authentication: Authorization: Bearer <user API key>, created on gptimage25api.com.
No login cookie is required for API requests. Do not send an OpenAI key or a login JWT.
Poll with the same key that submitted the job. SUCCESS returns data.response as image URLs.
No automatic generation retries or guaranteed idempotency. Credits per generation: 1K = 4, 2K = 6, 4K = 10, for both variants.

## Setup
1. Sign in or register on this site.
2. Open API keys, create a named key, and copy it into GPTIMAGE25_API_KEY on your server.
3. Check account credits before generation. Payment plans depend on the configured store.
4. Submit one generation, save data.task_id, and poll with the same key.
5. Download successful images to your storage promptly.
6. Delete unused keys. Finish polling existing jobs with their original key before deleting it during rotation.

## Parameters
- model (string): Optional. Must be gpt-image-2.5 when supplied. Uses GPT Image 2.5.
- variant (string): Optional. flare (default) or sunburst. Both support text-to-image and image-to-image.
- prompt (string): Required for both generation and editing: 1–20,000 characters after trimming.
- images (string[]): Optional, at most 16 public HTTP(S) image URLs for editing. URL credentials, base64 and local files are not accepted. Upload to accessible storage first. Aliases: input_urls, inputUrls.
- aspect_ratio (string): Optional, defaults to auto. Values: auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 27:16, 16:27, 9:8, 8:9. Alias: aspectRatio.
- resolution (string): Optional, defaults to 1K. Values: 1K, 2K, 4K (case-insensitive). All 13 aspect ratios support all three resolutions.
- public (boolean): Optional visibility flag; defaults to false in the existing backend. Aliases: is_public, isPublic. Set false for private tasks.
- client_request_id (string): Optional trace label: 12-80 letters, numbers, underscores or hyphens. Alias: clientRequestId. NOT an idempotency key: repeated POSTs can create and charge separate tasks.
Unknown fields are not forwarded. Credentials are accepted only in Authorization. No webhook/callback, streaming, batches, OpenAI SDK compatibility or permanent output storage is promised.

## Generate response (illustrative)
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n42YOUR_TASK_IDgptimg",
    "status": "IN_PROGRESS"
  }
}

## Status response (illustrative URLs, not a live result)
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n42YOUR_TASK_IDgptimg",
    "status": "SUCCESS",
    "consumed_credits": 4,
    "created_at": "2026-09-09 08:00:00",
    "error_message": null,
    "request": {
      "model": "gpt-image-2.5",
      "variant": "flare",
      "prompt": "Studio photograph of a translucent green glass chair",
      "aspect_ratio": "3:2",
      "resolution": "1K",
      "public": false
    },
    "response": [
      "https://your-image-storage.example/result.png"
    ]
  }
}
Before success, response can be null. request echoes the normalized input and GPT Image 2.5 variant. consumed_credits is the actual task credit value; failed/refunded tasks can report zero.

## Polling states
- SUBMITTING: Task is being submitted. Keep polling.
- PENDING: Task is queued. Keep polling.
- IN_PROGRESS: Task is generating. Keep polling.
- SUCCESS: Generation finished. Read data.response, an array of image URLs.
- FAILED: Generation failed. Inspect data.error_message and consumed_credits. Stop polling.
- REFUND_PENDING: Generation failed and its credit refund is pending. Check at a slower interval until FAILED.
Poll every 8 seconds with a bounded deadline and backoff. On timeout, retain task_id and resume later. Error responses may include data.task_id; persist it. If a POST times out without a task ID, check playground history or contact support before submitting again.

## Errors
Errors use HTTP status plus {code,message,data}. data can be null or include task_id and status.
- 400: Invalid JSON, missing input or unsupported parameter combination.
- 401: Missing, malformed, invalid, disabled or deleted API key.
- 402: Insufficient account credits.
- 403: Key is not authorized, or belongs to another project.
- 404: Task is not found for this key. Use the key that created it.
- 405: Wrong HTTP method. Generate requires POST; status requires GET.
- 415: Use Content-Type: application/json for generation.
- 429: Rate limited. Back off; never blindly repeat a generation POST.
- 502: Service unavailable or invalid upstream response.
- 503: Service configuration or temporary availability issue.
- 504: Request timed out. Generation may still have been accepted.
Other upstream 4xx/5xx statuses can be preserved. Handle unexpected failures.

## cURL
export GPTIMAGE25_API_KEY='YOUR_API_KEY'

curl --fail-with-body 'https://gptimage25api.com/api/v1/images/generate' \
  -H "Authorization: Bearer $GPTIMAGE25_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5",
    "variant": "flare",
    "prompt": "Studio photograph of a translucent green glass chair",
    "aspect_ratio": "3:2",
    "resolution": "1K",
    "public": false
  }'

# Use data.task_id from the response, with the SAME key.
curl --fail-with-body \
  'https://gptimage25api.com/api/v1/images/status?task_id=YOUR_TASK_ID' \
  -H "Authorization: Bearer $GPTIMAGE25_API_KEY"

## JavaScript (Node.js)
// Node.js 20+. Set GPTIMAGE25_API_KEY in your server environment.
const base = 'https://gptimage25api.com';
const key = process.env.GPTIMAGE25_API_KEY;
if (!key) throw new Error('Set GPTIMAGE25_API_KEY');
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));

async function request(path, body) {
  const res = await fetch(base + path, {
    method: body ? 'POST' : 'GET',
    headers: {
      Authorization: 'Bearer ' + key,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    ...(body ? { body: JSON.stringify(body) } : {}),
    signal: AbortSignal.timeout(75000),
  });
  const json = await res.json();
  if (!res.ok || json.code !== 200) {
    const error = new Error(json.message || 'Request failed');
    error.status = res.status;
    error.taskId = json.data?.task_id;
    throw error;
  }
  return json.data;
}

// Send ONCE. A timeout is not proof that the task was rejected.
const job = await request('/api/v1/images/generate', {
  model: 'gpt-image-2.5', variant: 'flare',
  prompt: 'Studio photograph of a translucent green glass chair',
  aspect_ratio: '3:2', resolution: '1K', public: false,
});
console.log('Keep this task ID:', job.task_id);
const deadline = Date.now() + 10 * 60 * 1000;
let complete = false;
while (Date.now() < deadline) {
  await sleep(8000);
  let result;
  try {
    result = await request('/api/v1/images/status?task_id='
      + encodeURIComponent(job.task_id));
  } catch (error) {
    if ([429, 502, 503, 504].includes(error.status)) {
      await sleep(16000);
      continue; // Retry status reads only.
    }
    throw error;
  }
  if (result.status === 'SUCCESS') {
    console.log(result.response); // Array of image URLs.
    complete = true;
    break;
  }
  if (result.status === 'FAILED')
    throw new Error(result.error_message || 'Generation failed');
  if (result.status === 'REFUND_PENDING') await sleep(22000);
}
if (!complete) throw new Error(
  'Polling stopped. Resume status checks for ' + job.task_id
  + '; do not automatically submit again.'
);

## Python
# Python 3.10+. Uses only the standard library.
import json, os, time
from urllib.request import Request, urlopen
from urllib.error import HTTPError
from urllib.parse import urlencode

BASE = "https://gptimage25api.com"
KEY = os.environ["GPTIMAGE25_API_KEY"]

def request(path, body=None):
    headers = {"Authorization": "Bearer " + KEY}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    req = Request(BASE + path, data=data, headers=headers,
                  method="POST" if body is not None else "GET")
    with urlopen(req, timeout=75) as response:
        result = json.load(response)
    if result["code"] != 200:
        raise RuntimeError(result.get("message", "Request failed"))
    return result["data"]

# Submit once; a timeout does not guarantee rejection.
job = request("/api/v1/images/generate", {
    "model": "gpt-image-2.5",
    "variant": "flare",
    "prompt": "Studio photograph of a translucent green glass chair",
    "aspect_ratio": "3:2", "resolution": "1K", "public": False,
})
task_id = job["task_id"]
print("Keep this task ID:", task_id)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    time.sleep(8)
    try:
        result = request("/api/v1/images/status?" +
                         urlencode({"task_id": task_id}))
    except HTTPError as error:
        if error.code in (429, 502, 503, 504):
            time.sleep(16)
            continue  # Retry status reads only.
        raise
    if result["status"] == "SUCCESS":
        print(result["response"])  # List of image URLs.
        break
    if result["status"] == "FAILED":
        raise RuntimeError(result.get("error_message") or "Failed")
    if result["status"] == "REFUND_PENDING":
        time.sleep(22)
else:
    raise TimeoutError("Resume status checks for " + task_id +
                       "; do not automatically submit again.")

## Privacy and operations
Call from your server, not browser code. Public CORS is not enabled. Never put keys in query strings, browser storage, telemetry or repositories.
Use public:false for private tasks. Image URLs must be reachable by the provider. Local files and private storage URLs cannot be fetched.
The generation backend handles credits and refunds. Refunds can be asynchronous; inspect REFUND_PENDING and consumed_credits. No delivery-time SLA, throughput quota or retention period is asserted.
This API uses GPT Image 2.5; it is not an official OpenAI endpoint.