How to Use gpt-image-2.5-flare@pro via the hiapi API: curl, Python, and a Working Request

gpt-image-2.5-flare@pro is one of the image models available through hiapi's unified task API. This guide walks through a minimal working request in curl and Python, then covers the parameters and patterns you need for production: callbacks, idempotency, and error handling.

What you'll need

• A hiapi API key. Grab one from the hiapi dashboard — every key is prefixed sk-.
• https://api.hiapi.ai as the base URL. Every request needs an Authorization: Bearer sk-<your-key> header.

Image generation on hiapi (and every other async model — video, TTS, music) runs through one endpoint: POST /v1/tasks. You create a task, then either poll GET /v1/tasks/:id or receive a callback when it finishes. Full reference: Unified Async API.

Minimal working example

curl

Create the task:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

This returns a task ID, not the image — image generation is asynchronous:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR" }
}

Poll for the result:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status moves through queued → handling → archiving → success (or fail). Once it's success, the image is at data.output[0].url:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt is a Unix timestamp — download or re-host the file before it passes, the URL stops working after that.

Python

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

Install the one dependency with pip install requests, export HIAPI_API_KEY, and run it.

Parameters that matter

gpt-image-2.5-flare ships two routes: the default route (use the bare model id gpt-image-2.5-flare) and the pro route (append @pro, as in every example above). There's no explicit @default suffix — passing one returns MODEL_UNAVAILABLE.

input accepts:

• prompt (string, required) — the only required field.
• aspect_ratio — 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, auto, or an explicit pixel size like 1536x1024, 2048x2048, 3840x2160.
• quality — low, medium, high, xhigh, max, or auto.
• output_format — png, jpeg, or webp.
• background — auto, transparent, or opaque. Use transparent with output_format: png or webp for a cutout asset.

The schema is strict — an unknown field (size, n, anything not listed above) returns 400 INVALID_REQUEST with additional properties '<field>' not allowed rather than being silently ignored. If you need to edit an existing image instead of generating from a blank prompt, hiapi exposes that as a separate model id — see the model page for the image-to-image variant.

Production patterns

Use a callback instead of polling. Add a callback object to the create request:

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final" is currently the only supported value — hiapi POSTs to your URL once, when the task reaches success or fail. The callback body is identical to the data field you'd get from GET /v1/tasks/:id.

Send an Idempotency-Key header. If a request times out on your end and you retry it, an idempotency key stops hiapi from creating (and billing) a second task for the same request.

Handle errors explicitly. An invalid or revoked key returns HTTP 401:

{
  "error": {
    "code": "permission_denied",
    "type": "hiapi_error",
    "message": "This API key is invalid...",
    "request_id": "..."
  }
}

A malformed input returns HTTP 400 with error_code: "INVALID_REQUEST" and a message naming the offending field — check that before retrying, retrying a 400 with the same body will just fail again.

Pricing for gpt-image-2.5-flare@pro (billed per successful image, by resolution and quality tier) is on the pricing page.

Related docs

• Unified Async API reference — full task lifecycle, all model types
• Create Task — request/response shape for POST /v1/tasks
• Get Task Detail — polling GET /v1/tasks/:id
• Authentication — API key format and headers
• gpt-image-2.5-flare@pro model page

FAQ

What's the difference between the default route and @pro? They're two separate routes of the same model family, selected by the model id you send (gpt-image-2.5-flare vs gpt-image-2.5-flare@pro). Check the model page and pricing for the current cost and capability difference before choosing.

Can I generate a transparent PNG? Yes — set "background": "transparent" with "output_format": "png" (or "webp").

Why did I get additional properties 'size' not allowed? The schema is strict. Use aspect_ratio (which also accepts explicit pixel dimensions like 1024x1024) instead of a size field.

How long does the output URL stay valid? Until the expireAt Unix timestamp on the output[0] object. Download or copy it to your own storage before then — hiapi doesn't keep serving it after that.

Do I have to poll if I set a callback? No, but you still can — GET /v1/tasks/:id works regardless of whether a callback is configured, useful for a manual recheck if your callback endpoint ever misses a delivery.

What happens if my request has both input_urls and a bad prompt? Validation runs on the whole payload before the task is created — any invalid field, including a malformed media array, returns 400 and no task (and no charge) is created.