GPT Image 2

GPT Image 2 supports text-to-image and image-to-image tasks with up to 16 reference images, plus OpenAI Images-compatible endpoints.

Model information

API Key channel

API Key authorization for gpt-image-2 can use Official API Relay or Subscription Direct. Official API Relay keeps the existing generation route; Subscription Direct now uses the upstream native OpenAI Images generations / edits endpoints without an LLM conversation or image_generation tool orchestration. Callers continue to send "model":"gpt-image-2" and must not send an internal routing model ID. Public endpoints, request fields, and task ID rules remain unchanged. All other media models remain Official API Relay-only.

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 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; Subscription Direct GPT Image 2 tasks are managed locally by the gateway and cannot be cancelled through the stop endpoint.
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. Official API Relay keeps the existing terminal-callback flow, while Subscription Direct waits directly for the upstream native Images response. 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 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" 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, 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 requests are billed only by Token usage after a successful terminal result. Prices are in USD per 1M tokens and currently apply equally to both API Key channels:

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. For Official API Relay, the callback handler or background poller stores upstream Base64 in OSS before settlement. For Subscription Direct, the native Images executor handles the response directly and likewise stores URL or Base64 results 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",
       "input":{"prompt":"a surreal painting of a banana in space","resolution":"1024x1024","quality":"high","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",
       "input":{"prompt":"convert to watercolor","images":["https://example.com/input.png"],"resolution":"1024x1024","quality":"medium","background":"transparent"}}'

Task creation responses

The asynchronous endpoint immediately returns a platform tsk_* ID. Subscription Direct uses the response below; Official API Relay keeps its existing successful upstream fields while rewriting task IDs to platform IDs:

{
  "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. For Subscription Direct edits, the gateway safely downloads these public or OSS URLs and submits them according to the upstream protocol after validating redirects, addresses, image formats, and the 30 MB limit.

Neither endpoint precharges. Official API Relay keeps the existing task-callback flow. Subscription Direct calls the upstream native images/generations and images/edits endpoints and waits directly for their responses, without an LLM conversation or image tool. 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. 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. Official API Relay settles from the successful terminal callback's result.usage, while Subscription Direct settles from the native Images response's 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.

Official API Relay 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. Subscription Direct waits up to 30 minutes for the native Images response. An upstream non-2xx response or timeout returns an OpenAI-compatible HTTP 424 error, and the corresponding asynchronous task enters a failed terminal state. 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","prompt":"a surreal painting of a banana in space","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", "prompt": "a red apple", "size": "1024x1024", "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. For Subscription Direct, every upstream image is first stored in OSS and the same validated bytes are returned as standard Base64 without a Data URL prefix or line breaks. If any image download, decode, or storage operation fails, the result is not delivered early. Image storage does not add any charge.

By default or with response_format="url", the compatible endpoints return a URL-form image response. Subscription Direct URLs always point to platform OSS:

{
  "background": "opaque",
  "created": 1785408333,
  "output_format": "png",
  "quality": "medium",
  "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","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",
            "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"])