GPT Image 2.5 API: Generate, Edit, and Migrate

To use GPT Image 2.5 on HiAPI, choose gpt-image-2.5-flare or gpt-image-2.5-sunburst and submit a task to POST /v1/tasks. Both models support generation and editing. Add image_urls when the request needs reference images; omit the field for generation from text alone.

Migrating from Image 2 requires updating both the model ID and the input fields. Existing routes have different conventions for resolution, size, and references. Replacing only the model string can leave incompatible parameters in your request.

The examples follow HiAPI's live documentation checked on September 9, 2026 and illustrate requests and asynchronous processing. Check actual outputs and charges in your task records. For contract updates, consult the Flare documentation and Sunburst documentation.

One model ID for generation and editing

Flare and Sunburst expose the same request fields on HiAPI. Omit image_urls for text-only generation. For editing, supply 1–16 references and describe what should change and what should remain. Do not send an empty array or invent /edit and /text-to-image suffixes for these model IDs. Each task produces one image.

If you already have a reliable image workflow, migrate one task category first and keep its existing inputs and acceptance criteria. See the Image 2 vs 2.5 overview for model positioning. This article focuses on the request lifecycle.

Submit a generation request

Save the following JSON as request.json. It describes a square product photograph of a mug. Setting quality explicitly to medium makes the request settings easier to reproduce. The value 1024x1024 is one of the documented pixel-size choices for aspect_ratio.

{
  "model": "gpt-image-2.5-flare",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

Keep the API key in a server-side environment variable named HIAPI_API_KEY. The command below submits the file and saves the creation response. Your application should generate HIAPI_REQUEST_ID for this logical request. Reuse it when retrying the same request after a network problem; use a new value when changing the input or creating another image.

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

After a successful submission, read data.taskId from created.json. The image is still being generated. Idempotency-Key prevents repeated submissions of the same logical request from creating multiple tasks; see the full rules in Create Task. A successful submission is not a completed image.

Edit an image through the same endpoint

This is a separate Sunburst editing request. Replace the placeholder in image_urls with a real reference URL that the service can read, save it as request.json, and submit it with a new request ID. The example.com address only illustrates the field structure and cannot be used as a working reference.

{
  "model": "gpt-image-2.5-sunburst",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

For multiple references, describe their roles in array order: for example, the first image supplies the product and the second supplies the setting. For successive edits, use the previous saved output as a reference in the next request. Each step is a new task with its own edit instruction. Do not assume the endpoint retains conversation or image history automatically.

For transparency, set background to transparent and choose PNG or WebP. JPEG cannot carry a transparent background. Inspect the edges and subject in the output; request settings do not replace visual acceptance.

Query status, then save the image

GET /v1/tasks/:id returns task details. queued, handling, and archiving are non-terminal states. success means the output is available; fail provides failure information in data.error. The outer code: 200 indicates that the query succeeded, so always inspect data.status as well. Get Task Detail

The Python example below uses requests, reads the saved created.json, waits three seconds, then polls every four seconds. It saves the task detail JSON and the first image. Its ten-minute local wait limit is an example policy, not a service SLA, and does not cancel the server-side task. If it times out, retain the task ID and resume querying that same task later.

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

Download or re-store temporary outputs before output[].expireAt. A production service can configure a top-level callback for terminal notifications and retain polling as a fallback. Do not place callback fields inside input. Implement callback signature verification and duplicate handling according to the Unified Async API. This example does not include a business queue, webhook service, or complete network retry policy.

Migrate the input contract from Image 2

Identify your current Image 2 route before converting its payload. The table describes differences between HiAPI contracts; it is not a direct migration recipe for another provider's SDK.

The current 2.5 ratio choices are 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, and auto. The same aspect_ratio field also accepts ten documented pixel dimensions. For fixed output dimensions, choose a listed value; the widthxheight syntax does not imply support for arbitrary sizes. The new documentation describes auto as letting the model choose a suitable composition. Do not assume it inherits the old editing route's input-following behavior.

Quality choices are low, medium, high, xhigh, max, and auto, with medium as the default. A matching quality name does not guarantee the same cost or visual result across models. For the old contracts, consult Image 2 generation and Image 2 editing.

Include errors and cost in acceptance

For a synchronous 400 response, check the model ID, fields, and enum values; for 402, check the balance; for 415, check Content-Type. If a created task reaches fail, retain data.error and investigate before resubmitting the same invalid input. Retry a 503 later with backoff. If a POST loses its connection and you cannot tell whether the task was created, reuse the original idempotency key. Creation errors

Start cost checks with the current HiAPI pricing page and the selected model page. During migration acceptance, record the full model ID, dimensions, quality, reference count, request, output, and actual bill. Do not carry over an Image 2 price or quote another provider's starting price as HiAPI pricing. Browser-generated images can help evaluate appearance; API latency and billing require their own records.

Integrate, save, and review one generation task and one editing task before expanding the batch workflow. Open Flare or Sunburst for the current model entry point, and maintain request parameters against its Docs page.