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/text-to-image only requires prompt in input. Aspect ratio defaults to auto and resolution to 1K.

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/text-to-image",
    "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/text-to-image",
    "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/text-to-image",
        "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", "fail"):
        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 has two model ids: gpt-image-2.5-sunburst/text-to-image for generating from a prompt, and gpt-image-2.5-sunburst/image-to-image for editing or compositing reference images. Both take the same fields, except that image_urls is required on image-to-image and not used on text-to-image:

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/image-to-image",
    "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"],
      "resolution": "2K"
    }
  }'

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/text-to-image",
  "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 fail). 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. Send an Idempotency-Key header (up to 255 bytes) with the create request and reuse the same key when you retry: the same account and key create only one task, and the retry returns the original taskId. Without it, 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).
• fail — inspect data.error 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 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 two model ids. Use gpt-image-2.5-sunburst/image-to-image with image_urls (1–16 reference images) to edit or composite, and gpt-image-2.5-sunburst/text-to-image to generate from text alone.

What happens if I send an empty image_urls array instead of omitting it? Don't. On image-to-image, image_urls is required and needs at least one URL. For text-only generation, switch to the text-to-image model id instead.

How much does one image cost? It depends on resolution: $0.05 at 1K, $0.08 at 2K, and $0.12 at 4K, the same for text-to-image and image-to-image. During the Programmers' Day offer (until November 9, 2026, 00:00 UTC+8) every tier is 50% off: $0.025, $0.04, and $0.06. Check the model page for the live price 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.