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

To generate or edit images with gpt-image-2.5-sunburst, submit a task to POST /v1/tasks with your prompt, then poll GET /v1/tasks/<id> (or receive a callback) until the task finishes and read the image URL from data.output[0].url. This guide covers the minimal request, the full parameter set, and the production patterns (callbacks, idempotency, error handling) you need before shipping it.

Prerequisites

You need a hiapi API key. Create one from the dashboard — every request authenticates with Authorization: Bearer sk-<your-key>. There is no free-tier way to call this from a browser or without a key; all examples below assume you already have one.

Minimal working example

gpt-image-2.5-sunburst only requires prompt in input. Everything else — aspect ratio, quality, output format — has a default.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "input": {
      "prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter, soft morning light"
    }
  }'

That returns a task id immediately:

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

Poll for the result:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

Python version of the same round trip:

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst",
        "input": {"prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "failed"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url points to temporary storage — the response includes an expireAt (Unix seconds). Download the bytes and persist them (your own storage, S3, R2, etc.) before that deadline; don't treat it as a permanent link.

Full parameter reference

gpt-image-2.5-sunburst uses one model id for both text-to-image and image editing — it switches mode based on whether you pass image_urls:

Editing example — pass one or more reference images and describe only the change you want:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "input": {
      "prompt": "Change only the ceramic cup color to matte black. Keep the marble counter, lighting, and camera angle exactly as-is.",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "quality": "high",
      "output_format": "png"
    }
  }'

The schema is strict (additionalProperties: false) — unknown fields are rejected, so don't carry over parameters from other image models (e.g. size, strength, n).

Production patterns

Use a callback instead of polling in a real backend. Add a callback block to skip the poll loop:

{
  "model": "gpt-image-2.5-sunburst",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-server.example.com/hooks/hiapi", "when": "final"}
}

when: "final" fires exactly once, when the task reaches a terminal state (success or failed). Your endpoint should respond 2xx quickly and do the real work (download the output, update your own DB) asynchronously — hiapi retries callbacks that don't get a fast ack.

Make retries idempotent. If a request times out client-side, you don't know whether the task was created. Store your own idempotency key alongside the returned taskId before you do anything else, and check for an existing task before submitting a duplicate — reprocessing the same prompt twice bills twice.

Handle the terminal states you'll actually see:

• success — read data.output[0].url and download promptly (respect expireAt).
• failed — inspect data for the failure reason before retrying; don't retry blindly on every failure, some are prompt-level (e.g. policy violations) and will fail again unchanged.
• Polling a task id that doesn't exist (typo, expired) returns HTTP 404 with {"code":404,"message":"task not found"}.

Auth failures are HTTP 401, not a task-level error:

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

Check this in your error handling before you assume a failed task — an invalid or revoked key never reaches task creation at all.

Related reading

• GPT Image 2.5 Sunburst model page — live examples and current per-tier pricing.
• GPT Image 2.5: Generate, Edit, and Migrate — if you're moving from the older Image 2 routes to the 2.5 family (Flare or Sunburst), this covers the parameter differences.
• How to Restyle Images with AI — a broader image-to-image walkthrough if Sunburst's editing mode is only part of your pipeline.
• Authentication docs and Quick Start for the full request lifecycle beyond this one model.

FAQ

Does gpt-image-2.5-sunburst support image editing, or only text-to-image? Both, through the same model id. Add image_urls (1–16 reference images) to edit or composite; omit it entirely to generate from text alone.

What happens if I send an empty image_urls array instead of omitting it? Don't — the field has minItems: 1. Either include at least one URL or leave the field out of the request.

How much does one image cost? It depends on quality. low is the cheapest tier, medium is the default, and high/xhigh/max cost progressively more per image. Check the model page for current per-tier pricing before scaling up.

Can I get a fixed pixel size instead of an aspect ratio? Yes — aspect_ratio also accepts literal sizes like 1024x1024, 1536x1024, or 3840x2160, in addition to ratio strings like 16:9.

Why did my task return 404 when I polled it? Either the taskId has a typo, or you're polling an endpoint/region that doesn't have that task. Double-check the id you stored from the creation response — hiapi does not silently expire task records within any normal polling window.

Can I call this without an API key for testing? No. Every /v1/tasks request requires Authorization: Bearer sk-<key>; there's no anonymous or browser-only mode.