How to Call gpt-image-2.5-sunburst/text-to-image via the HiAPI API: curl and Python

What this model endpoint gives you

gpt-image-2.5-sunburst/text-to-image is an image-generation model exposed through HiAPI's unified API. You address it by its model ID, send a prompt in the same chat-completions-shaped request body you already use for text models, and get generated image data back in the response.

The practical consequence: if your codebase already talks to HiAPI for text, there is no second SDK, no separate authentication scheme, and no new endpoint family to learn. The model ID is the only thing that changes.

Pick this endpoint when your task is prompt-to-image generation — producing a new image from a text description, optionally steered by reference images you supply in the request. If you need to analyze or describe an existing image rather than produce one, a vision-capable chat model is the better fit; keep image generation on this endpoint and image understanding elsewhere.

One expectation to set early: image calls are slower than text completions. A response that takes a single-digit number of seconds is normal, and your client timeouts should be tuned for that reality rather than inherited from a text-only setup.

Before you send the first request

Three things need to be in place.

An API key

Create a key in your HiAPI account and store it as an environment variable rather than in source code:

export HIAPI_API_KEY="your-key-here"

The exact model ID

The string is gpt-image-2.5-sunburst/text-to-image. Treat it as an opaque identifier — copy it, don't retype it from memory. The slash is part of the ID. A typo here is the single most common cause of a failed first call, and it surfaces as a model-not-found style error rather than a payload problem.

A client that can issue HTTPS requests

For the first verification you only need curl, which is preinstalled on most systems. For application code, Python with the requests library (or any HTTP client) is enough. Nothing about this endpoint requires a specialized image library on the client side; you are posting JSON and reading JSON back.

You do not need to pre-upload images or provision storage before your first text-only call. Start with the minimal request below and add reference images only after the basic round trip works.

A minimal working request with curl

Here is the smallest correct invocation:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
      {
        "role": "user",
        "content": "A sunlit coastal cliff at golden hour, wide angle, high detail"
      }
    ]
  }'

Walking through the fields:

• URL — the standard HiAPI chat-completions path. Image models use the same route as text models.
• Authorization — bearer token with your API key. If this header is malformed you get a 401 before the model is ever consulted.
• Content-Type — must be application/json.
• model — the exact model ID from the previous section.
• messages — a standard array of role/content objects. Your prompt is the content of the user message.

On success you receive a JSON response containing the generated image data alongside the usual completion metadata. Save the raw response to a file first and inspect it before wiring parsing logic into a script:

curl -sS ... -o response.json

Once this returns an image, your credentials and payload shape are correct, and every later problem is application logic rather than setup.

The same request in Python

The request contract does not change — only client setup, timeouts, and response handling do.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
        {
            "role": "user",
            "content": "A sunlit coastal cliff at golden hour, wide angle, high detail",
        }
    ],
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 180),  # connect, read
)

response.raise_for_status()
data = response.json()
print(data)

Three details worth noticing:

Timeouts are explicit and asymmetric

The tuple (10, 180) sets a short connect timeout and a generous read timeout. Image generation legitimately takes a while; a single flat timeout copied from a text client will produce spurious failures. The connect timeout stays short so a network problem fails fast.

json=payload not data=

Passing a dict via json= handles serialization and sets the content type for you. If you pass a pre-serialized string with data=, set the header manually.

Parse defensively

The response is JSON; log the whole body on unexpected shapes before indexing into it. Do not assume a fixed nesting depth until you have seen a real response — and never assume a success shape on a non-2xx status.

If you prefer a client library configured for HiAPI, the payload you send is identical; only the call site changes.

Passing reference images correctly

Reference images are supplied inside the message content, not as top-level ad-hoc fields. This is the part of the integration most likely to go subtly wrong, because a malformed reference usually does not error — the request simply succeeds and the output ignores your image.

Keep the payload structure consistent across languages: the user message carries a content array, where a text part holds your prompt and image parts carry the reference data. The same JSON body you build in Python must be byte-for-byte expressible in curl; if you cannot write the curl equivalent of a Python payload, the structure has drifted.

When results appear to ignore your reference image, check in this order:

1. Placement. Is the image part inside messages[].content, or did it leak to the top level of the body? The model only sees what is in the message.
2. Encoding. Reference images travel as encoded data in the request. Confirm the data is complete and correctly formatted rather than truncated by a manual splice or a bad copy-paste.
3. Prompt coupling. A reference image steers generation; it does not replace the instruction. Say explicitly what role the image plays — style, composition, subject — instead of assuming the model infers it.
4. Size. Very large references bloat the request and slow the round trip. Downscale to what the task actually needs before encoding.

A practical debugging habit

Build the reference-image payload once, save the exact JSON body that worked, and reuse it as a fixture. When a call misbehaves later, diff your current body against the fixture. Most reference-image regressions are structural, and a diff finds them in seconds.

Handling errors, timeouts, and retries

Image endpoints fail differently from text endpoints: they are slower, so more calls fall into the window where a timeout fires, and the cost of a blind retry is higher because the work is heavier.

Separate client errors from transient failures

• 4xx (except 429) — malformed payload, bad model ID, missing auth. Retrying the same request will fail identically. Fix the request.
• 401/403 — credential problem. Check the key and the Authorization header format.
• 429 — rate limited. Retry, but with backoff and jitter, not immediately.
• 5xx and connection errors — transient. Retry.
• Read timeout — ambiguous: the generation may have completed server-side. Treat a timeout as retryable only if your workflow tolerates a possible duplicate.

Retry only what is safe

Use exponential backoff with jitter and a small cap on attempts — three is usually enough. A simple pattern:

import time, random

def post_with_retry(session, url, payload, attempts=3):
    for i in range(attempts):
        try:
            r = session.post(url, json=payload, timeout=(10, 180))
            if r.status_code == 429 or r.status_code >= 500:
                raise RuntimeError(f"retryable: {r.status_code}")
            r.raise_for_status()
            return r.json()
        except (RuntimeError, requests.ConnectionError, requests.Timeout):
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.random())

Do not retry 4xx payload errors inside this loop — surface them immediately so a bad request fails loudly instead of burning attempts.

Size the timeout to the model

Give image calls a read timeout several times larger than your text default, and set it per call rather than globally so text traffic is not penalized. If your platform has a hard request ceiling, keep generation prompts and reference images within the budget you can actually complete.

Production checklist before you ship

A short list that prevents most incidents:

• Model ID in one place. Define gpt-image-2.5-sunburst/text-to-image as a constant or config value, not scattered string literals.
• Key from environment, never committed. Rotate it like any other secret.
• Explicit timeouts with a generous read window, set on the request rather than the session default.
• Retries on 429/5xx/timeouts only, with backoff and jitter, and a bounded attempt count.
• Full response logging on failure — log status, body, and request ID before parsing, so a support conversation starts with evidence.
• A saved working payload fixture for both the plain and reference-image cases, used for diffing when behavior changes.
• Reference images inside message content, downscaled to the task, with the prompt stating their role.
• A smoke test in CI that issues one real call against the model ID, so a renamed or retired model surfaces before users find it.

None of these habits are specific to image generation, but each one addresses a failure mode that image calls hit more often than text calls. Wire them in once, and the endpoint behaves like any other part of your stack. For the model's current parameters and limits, check the model page on HiAPI before you finalize your config.