GPT Image 2.5

GPT Image 2.5 supports text-to-image and image-to-image tasks with up to 16 reference images, plus OpenAI Images-compatible endpoints. Compared with GPT Image 2, quality adds the xhigh and max levels.

Model information

API Key channel

GPT Image 2.5 API Key authorization uses Official API Relay only. Callers send "model":"gpt-image-2.5-flare" or "model":"gpt-image-2.5-sunburst" and must not send an internal routing model ID. Public endpoints, request fields, and task ID rules are the same as gpt-image-2.

Task workflow

1. Prepare input media. Image-to-image inputs must be publicly reachable direct HTTPS URLs, with up to 16 URLs. The OpenAI-compatible edits endpoint documented later also accepts multipart png/jpg/webp uploads. Local files, Base64 / Data URLs, and existing remote URLs can be converted to a public fileUrl with HopsAPI file uploads. Do not pass asset://, s3://, file://, or private-network URLs directly.
2. Create an asynchronous task. Send the model-specific task, model, and input fields below to POST /v1/router/task/create. This endpoint immediately returns a platform task_id in tsk_* format for every supported media model. GPT Image 2.5 ignores a top-level mode sent by legacy clients. Optional callback_url receives a signed webhook when the task finishes. See Media task callbacks. That URL is not forwarded upstream.
3. Poll the task. Save the returned ID and call GET /v1/router/tasks/{task_id} every 3–5 seconds until the task reaches a terminal status. To stop a queued or processing task, send {"task_id":"tsk_..."} to POST /v1/router/task/stop. An API key can only query or cancel tasks owned by the same buyer.
4. Use the OpenAI-compatible endpoints when needed. Send text-to-image requests to POST /v1/images/generations, or upload local multipart images to POST /v1/images/edits. Neither endpoint precharges. Results are returned only after asset storage and Token settlement succeed. response_format="url" returns URLs and response_format="b64_json" returns Base64. Task, storage, or settlement failures use an OpenAI-compatible error, and the maximum wait is 30 minutes.

Failure responses are intentionally neutral and do not expose upstream details. Use the request id in Provider error (request id: aitk-...) to correlate server logs; do not depend on error_message, fail_reason, or message for provider diagnostics. Every GPT Image 2.5 entry point is billed only from successful terminal Token usage; failed or cancelled tasks are not charged.

Every media request requires at least 1 credit of available media balance after outstanding image charges are excluded. If the full postpaid charge exceeds the available balance at settlement time, the gateway collects the available amount (never less than 1 credit) and delivers the result; if less than 1 credit is available, settlement waits for a retry and the result is not delivered.

Use model="gpt-image-2.5-flare" or model="gpt-image-2.5-sunburst" for both text-to-image and image-to-image. The general asynchronous task endpoint ignores top-level mode and reads native image parameters from input. input.resolution may be omitted, set to auto, or use a pixel size such as 1024x1024. input.quality supports low, medium, high, xhigh, max, or auto and defaults to auto. Asynchronous tasks do not support input.aspect_ratio; sending it returns HTTP 400. Image-to-image images accepts up to 16 public HTTPS URLs.

Task request parameters

Asynchronous task billing

All GPT Image 2.5 requests are billed only by Token usage after a successful terminal result. Prices are in USD per 1M tokens:

The gateway applies the existing platform settlement, reseller quote, and user pricing coefficients after calculating the Token amount.

Asynchronous tasks do not expose response_format; task queries always return platform OSS URLs. The callback handler or background poller stores upstream Base64 in OSS before settlement. Full input, cached-input, and output token counts are written to Usage, while persisted task results and GET /v1/router/tasks/{task_id} use the same compact shape: task_id, status, results[].urls, and cost after success. Queries only read the saved result and never upload Base64 on demand. A storage or settlement failure does not make the result deliverable or billable; queries and the background poller retry settlement idempotently.

Asynchronous task request examples

# Text-to-image
curl https://hopsapi.com/v1/router/task/create \
  -H "Authorization: Bearer sk-YOUR_KEY" -H "content-type: application/json" \
  -d '{"task":"Txt2Img","model":"gpt-image-2.5-flare",
       "input":{"prompt":"a surreal painting of a banana in space","resolution":"1024x1024","quality":"xhigh","background":"transparent"}}'

# Image-to-image
curl https://hopsapi.com/v1/router/task/create \
  -H "Authorization: Bearer sk-YOUR_KEY" -H "content-type: application/json" \
  -d '{"task":"Img2Img","model":"gpt-image-2.5-sunburst",
       "input":{"prompt":"convert to watercolor","images":["https://example.com/input.png"],"resolution":"1024x1024","quality":"max","background":"transparent"}}'

Task creation responses

The asynchronous endpoint immediately returns a platform tsk_* ID:

{
  "code": 200,
  "message": "success",
  "task_id": "tsk_mabc1234_0123456789abcdef01234567"
}

Save task_id and poll GET /v1/router/tasks/{task_id} every 3–5 seconds.

While an async task is still being prepared for delivery, results is empty and cost is omitted:

{
  "task_id": "tsk_mabc1234_0123456789abcdef01234567",
  "status": 1,
  "results": []
}

After an asynchronous task succeeds and Token settlement completes, queries use the following compact task shape. cost is the actual credit charge after platform settlement, reseller quote, and user pricing coefficients:

{
  "task_id": "tsk_mabc1234_0123456789abcdef01234567",
  "status": 2,
  "results": [{ "urls": ["https://assets.example.com/result.png"] }],
  "cost": 1.25
}

Failed and cancelled tasks use status 3 or 4; cost is omitted, and results is normally empty. Failure responses are intentionally neutral and do not expose upstream details. Use the request id in Provider error (request id: aitk-...) to correlate server logs.

OpenAI-compatible endpoints

POST /v1/images/generations accepts the existing OpenAI Images text-to-image request fields. POST /v1/images/edits accepts multipart image-to-image requests and JSON requests with an images array, where each item is {"image_url":"https://..."}. JSON accepts 1–16 public HTTP(S) reference images and preserves their array order. Multipart image / image[] fields continue to accept local png/jpg/webp files, which are uploaded temporarily before generation.

Neither endpoint precharges, and both settle from the successful terminal callback's usage. Successful top-level fields such as size, quality, background, output_format, and usage are preserved. Images in data[] are stored in OSS and Token settlement must complete before delivery. The response is not wrapped with platform task_id, status, or cost fields. Failures continue to use an OpenAI-compatible error object.

Set model to gpt-image-2.5-flare or gpt-image-2.5-sunburst. size accepts "auto" or "1024x1024" or "1536x1024" or 5 more values.

The size of the generated images. Arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model’s current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models.

Token billing for compatible endpoints

POST /v1/images/generations and POST /v1/images/edits make no precharge and settle from the successful terminal callback's result.usage. Text input, image input, and image output use their respective Token prices above, and orchestration LLM Tokens are always zero. The gateway converts the official USD amount at $1 = 100 credits and applies the existing platform settlement, reseller quote, and user pricing coefficients. Missing usage, inconsistent token details, non-zero text output Tokens, storage failure, less than 1 credit of available balance, or a usage-recording failure prevents delivery of the successful result.

Each call is recorded at its exact fractional-credit charge. Once unsettled compatible-image usage reaches at least 10 credits, multiple usage records are combined into one whole-credit wallet charge. Any fractional remainder stays on the oldest partially settled record and is carried into the next batch. On the Usage page, Settled shows how much of each record has entered a successful wallet batch; it is 0 before settlement, and the last record in a batch may be only partially settled.

The gateway waits up to 30 minutes for a billable terminal callback. A callback timeout returns HTTP 504; the task keeps running, remains queryable through GET /v1/router/tasks/{task_id}, and a later successful callback is still billed. For tasks created through a compatible endpoint, queries read the persisted URL-form result and do not repeat the synchronous b64_json conversion.

# Text-to-image generation
curl https://hopsapi.com/v1/images/generations \
  -H "Authorization: Bearer sk-YOUR_KEY" -H "content-type: application/json" \
  -d '{"model":"gpt-image-2.5-flare","prompt":"a surreal painting of a banana in space","quality":"xhigh","background":"transparent"}'

# Generation: read the image response directly
import requests

result = requests.post(
    "https://hopsapi.com/v1/images/generations",
    headers={"Authorization": "Bearer sk-YOUR_KEY"},
    json={"model": "gpt-image-2.5-flare", "prompt": "a red apple", "size": "1024x1024", "quality": "xhigh", "background": "transparent"},
    timeout=31 * 60,
).json()
print(result["data"][0]["url"], result["usage"])

Set response_format to b64_json in either JSON or multipart requests when the client needs inline image bytes. Storage does not add any charge, and the result is not delivered early if a storage operation fails.

By default or with response_format="url", the compatible endpoints return a URL-form image response pointing to platform OSS:

{
  "background": "opaque",
  "created": 1785408333,
  "output_format": "png",
  "quality": "xhigh",
  "size": "1672x941",
  "data": [
    {
      "url": "https://assets.example.com/result.png"
    }
  ],
  "usage": {
    "input_tokens": 15,
    "input_tokens_details": {
      "cached_tokens": 0,
      "image_tokens": 0,
      "text_tokens": 15
    },
    "output_tokens": 196,
    "output_tokens_details": {
      "image_tokens": 196,
      "text_tokens": 0
    },
    "total_tokens": 211
  }
}

# Image-to-image edits; repeat image up to 16 times.
curl https://hopsapi.com/v1/images/edits \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -F image=@input.png -F prompt="convert to watercolor style" -F size=1024x1024 \
  -F background=transparent

# Image-to-image edits with JSON reference URLs; images are used in array order.
curl https://hopsapi.com/v1/images/edits \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-image-2.5-sunburst","images":[{"image_url":"https://example.com/subject.png"},{"image_url":"https://example.com/style.jpg"}],"prompt":"preserve the subject and apply the reference style","size":"1024x1024"}'

# Image-to-image edits: read the image response directly
import requests

with open("input.png", "rb") as image:
    result = requests.post(
        "https://hopsapi.com/v1/images/edits",
        headers={"Authorization": "Bearer sk-YOUR_KEY"},
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "convert to watercolor style",
            "size": "1024x1024",
            "background": "transparent",
        },
        files={"image": ("input.png", image, "image/png")},
        timeout=31 * 60,
    ).json()

print(result["data"][0]["url"], result["usage"])