GPT Image 2.5 Sunburst Text-to-Image API: A Working curl and Python Guide

If you want to generate images with gpt-image-2.5-sunburst/text-to-image through the hiapi API, this guide walks through a complete, working request in both curl and Python — from creating a task to downloading the final image URL. Every request/response shown here was run against the live API before publishing.

Prerequisites

• A hiapi account with an API key (sk-...). Grab one from your hiapi dashboard.
• curl, or Python 3.8+ if you're following the Python example.
• Budget for at least one output image. gpt-image-2.5-sunburst/text-to-image is priced by output resolution — see current pricing before you run this in production, since rates can change.

All requests use the standard header:

Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

Minimal working example

hiapi's image models run on a single async task API: you POST a task, then poll (or get a webhook callback) until it reaches a terminal status, then read the image URL out of output[0].url.

1. Create the task (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product shot of a ceramic coffee dripper on a marble counter, soft morning light, 35mm lens look",
      "resolution": "2K",
      "aspect_ratio": "4:3",
      "background": "auto"
    }
  }'

A successful call returns just a task ID — generation happens asynchronously:

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

2. Poll for the result

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

Keep polling every few seconds until data.status is a terminal value. On success, the response looks like this (taskId/URL shortened for readability):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01ABCDEF...",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "status": "success",
    "storage": "temp",
    "created": 1789144334,
    "completed": 1789144407,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../output-0.png",
        "artifactId": "146251",
        "expireAt": 1789749206
      }
    ]
  },
  "message": "success"
}

Grab the image from data.output[0].url. That URL expires (see expireAt, a Unix timestamp) — download the bytes and store them yourself as soon as the task succeeds instead of treating it as a permanent link.

3. End-to-end in Python

import time
import requests

API_KEY = "sk-your-api-key-here"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(prompt: str, resolution: str = "1K", aspect_ratio: str = "1:1") -> str:
    payload = {
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 300, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task("A minimalist product shot of a ceramic coffee dripper on a marble counter")
    task = wait_for_task(task_id)
    image_url = task["output"][0]["url"]
    print(f"Done: {image_url}")

    img_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(img_bytes)

What's actually accepted in input

gpt-image-2.5-sunburst/text-to-image has a small, strict schema. Only these fields are accepted — anything else (quality, size, n, output_format, style, seed) gets rejected with a 400:

Note this is a separate schema from the bare gpt-image-2.5-sunburst model, which instead takes a quality tier (low/medium/high/xhigh/max/auto) and supports image-to-image editing via image_urls. The two are priced differently too — check the values against /en/pricing before you rely on a specific number, since rates are subject to change.

Production patterns

Webhook callback instead of polling

For anything beyond a quick script, skip polling and let hiapi call you back when the task finishes. Add a top-level callback object to the same POST /v1/tasks request:

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

when: "final" is currently the only supported value — your endpoint gets called once, when the task reaches a terminal state (success or fail), with the same payload shape you'd get from polling.

Polling vs. callback: polling is simpler to get right in a script or notebook and doesn't require a public endpoint, but it wastes requests and adds latency (average of your poll interval) before you notice completion. A callback is the better fit for a server-side integration or anything running at volume — you avoid the polling loop entirely and get notified the instant the task lands.

Idempotency on retries

The task API accepts a top-level idempotency_key string alongside model/input/callback. If your client might retry a POST after a timeout (you sent the request, but never got a response), attach a stable key so you have a clean signal to reconcile against instead of guessing whether the original request actually landed.

Handling errors

An invalid or expired API key returns HTTP 401 with a structured error body:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "request_id": "2026...",
    "type": "hiapi_error"
  }
}

A bad input value (wrong enum member, missing prompt, unsupported field) returns HTTP 400 before a task is ever created — so you're not charged for it:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Check for both cases explicitly: retry on transient network/5xx errors, but treat 400s as a signal to fix your request body, not something to retry blindly.

Related resources

• gpt-image-2.5-sunburst model page — full parameter reference and live pricing for both the bare model and the /text-to-image route.
• hiapi pricing — current per-resolution rates for this and every other model.
• GPT Image 2.5 Sunburst prompt recipes — worked prompt examples if you want inspiration before you start scripting.

FAQ

Do I need to specify resolution? No — it defaults to 1K if you omit it. Set it explicitly if you need 2K or 4K output, since price scales with resolution.

Can I pass quality like the docs for other GPT Image models show? Not on this route. gpt-image-2.5-sunburst/text-to-image rejects quality entirely — that parameter only exists on the bare gpt-image-2.5-sunburst model id, which has a different schema and pricing.

Why did my request return a task ID instead of the image directly? Every image model on hiapi runs through the same async task API (POST /v1/tasks → poll or callback → output[0].url), regardless of how fast the underlying model actually is. Build your integration around that pattern once and it works the same way for every model you swap in later.

What happens if I don't download the output URL in time? It expires — the expireAt field in the task response is a Unix timestamp for when the temporary URL stops working. Download and store the bytes yourself as soon as status is success.

Can I do image-to-image editing with this model? Not on the /text-to-image route. For image editing, use the bare gpt-image-2.5-sunburst model id with an image_urls input field — check its model page for the exact schema.

Ready to try it yourself? Grab an API key from your hiapi dashboard and swap the prompt in the Python example above.