GPT Image 2.5 Sunburst Text-zu-Bild-API: einsatzbereiter Leitfaden mit curl und Python

Wenn Sie über die hiapi-API mit gpt-image-2.5-sunburst/text-to-image Bilder generieren möchten, führt Sie dieser Leitfaden durch eine vollständige und funktionsfähige Anfrage – jeweils mit curl und mit Python – von der Erstellung des Tasks bis zum Herunterladen der finalen Bild-URL. Jede hier gezeigte Anfrage bzw. Antwort wurde vor der Veröffentlichung tatsächlich gegen die Live-API ausgeführt.

Voraussetzungen

• Ein hiapi-Konto und ein API-Key (sk-...). Erhältlich in der hiapi-Konsole.
• curl oder, wenn Sie die Python-Beispiele nachvollziehen möchten, Python 3.8+.
• Budget für mindestens ein Ausgabebild. gpt-image-2.5-sunburst/text-to-image wird nach Ausgabauflösung abgerechnet – prüfen Sie vor dem Betrieb in der Produktion die aktuelle Preisgestaltung, da sich die Tarife ändern können.

Alle Anfragen verwenden die Standard-Header:

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

Minimales funktionsfähiges Beispiel

Alle Bildmodelle von hiapi laufen über dieselbe asynchrone Task-API: Sie erstellen einen Task per POST und fragen dann per Polling ab (oder erhalten einen Webhook-Callback), bis er einen Endzustand erreicht, und lesen anschließend die Bild-URL aus output[0].url.

1. Task erstellen (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"
    }
  }'

Ein erfolgreicher Aufruf gibt lediglich eine Task-ID zurück – die Generierung erfolgt asynchron:

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

2. Ergebnis abfragen

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

Fragen Sie alle paar Sekunden weiter ab, bis data.status einen Endzustand erreicht. Bei Erfolg sieht die Antwort wie folgt aus (taskId/URL zur besseren Lesbarkeit gekürzt):

{
  "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"
}

Rufen Sie das Bild aus data.output[0].url ab. Diese URL läuft ab (siehe expireAt, einen Unix-Zeitstempel) – laden Sie die Bytes nach erfolgreichem Task sofort herunter und speichern Sie sie selbst; behandeln Sie die URL nicht als dauerhaften Link.

3. Python-End-to-End-Beispiel

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)

Welche Felder input tatsächlich akzeptiert

Das Schema von gpt-image-2.5-sunburst/text-to-image ist klein und strikt. Es werden nur die folgenden Felder akzeptiert – jedes andere Feld (quality, size, n, output_format, style, seed) wird mit 400 abgelehnt:

Feld	Pflicht	Werte
prompt	Ja	Beliebige Zeichenkette
resolution	Nein (Standard 1K)	1K, 2K, 4K
aspect_ratio	Nein	auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 27:16, 16:27, 9:8, 8:9
background	Nein	transparent, opaque, auto

Beachten Sie, dass dies nicht dasselbe Schema ist wie beim reinen Modell gpt-image-2.5-sunburst: Dieses akzeptiert quality-Stufen (low/medium/high/xhigh/max/auto) und unterstützt Bild-zu-Bild-Bearbeitung über image_urls. Auch die Preisgestaltung beider Varianten unterscheidet sich – bevor Sie sich auf konkrete Zahlen verlassen, prüfen Sie diese unter /en/pricing, da sich die Tarife ändern können.

Produktionsmuster

Webhook-Callbacks statt Polling verwenden

Für alles, was über ein schnelles Skript hinausgeht, überspringen Sie das Polling und lassen Sie hiapi Sie benachrichtigen, wenn der Task abgeschlossen ist. Fügen Sie dazu demselben POST /v1/tasks-Request ein callback-Objekt auf oberster Ebene hinzu:

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

when: "final" ist derzeit der einzige unterstützte Wert – wenn der Task einen Endzustand (success oder fail) erreicht, wird Ihr Endpunkt einmal aufgerufen, und die Nutzlast entspricht der beim Polling erhaltenen Antwort.

Polling vs. Callback: Polling ist in Skripten oder Notebooks einfacher korrekt umzusetzen und erfordert keinen öffentlich erreichbaren Endpunkt, verschwendet aber Requests und erhöht die Latenz (im Durchschnitt um Ihr Polling-Intervall), bis Sie vom Abschluss erfahren. Für serverseitige Integrationen oder jedes Szenario mit hoher Nebenläufigkeit ist der Callback besser geeignet – Sie umgehen die Polling-Schleife vollständig und werden benachrichtigt, sobald der Task abgeschlossen ist.

Idempotenz bei Wiederholungen

Die Task-API akzeptiert eine Zeichenkette idempotency_key auf oberster Ebene, neben model/input/callback. Falls Ihr Client den POST nach einem Timeout erneut versuchen könnte (Sie haben die Anfrage gesendet, aber nie eine Antwort erhalten), hängen Sie einen stabilen Key an – so haben Sie ein klares Signal zum Abgleich, statt zu raten, ob die ursprüngliche Anfrage tatsächlich angekommen ist.

Fehler behandeln

Ein ungültiger oder abgelaufener API-Key führt zu HTTP 401 und einem strukturierten Fehlerkörper:

{
  "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"
  }
}

Fehlerhafte input-Werte (ungültige Enum-Werte, fehlendes prompt, nicht unterstützte Felder) führen zu HTTP 400, bevor der Task erstellt wird – Ihnen wird also nichts berechnet:

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

Prüfen Sie beide Fälle explizit: Wiederholen Sie vorübergehende Netzwerk-/5xx-Fehler, aber betrachten Sie 400 als Signal, den Request-Body zu korrigieren, statt blind zu wiederholen.

Verwandte Ressourcen

• Modellseite von gpt-image-2.5-sunburst – vollständige Parameterreferenz und Live-Preise für das reine Modell und die Route /text-to-image.
• hiapi-Preise – aktuelle auflösungsabhängige Tarife für dieses und alle anderen Modelle.
• Prompt-Rezepte für GPT Image 2.5 Sunburst – wenn Sie vor dem Schreiben des Skripts Inspiration suchen, finden Sie hier Prompt-Beispiele als Anhaltspunkte.

Häufige Fragen

Muss ich resolution angeben? Nein – wird es weggelassen, gilt standardmäßig 1K. Wenn Sie 2K- oder 4K-Ausgaben benötigen, setzen Sie es explizit, da der Preis mit steigender Auflösung zunimmt.

Kann ich quality übergeben, wie in der Dokumentation anderer GPT-Image-Modelle? Auf dieser Route nicht. gpt-image-2.5-sunburst/text-to-image lehnt quality vollständig ab – dieser Parameter existiert nur bei der reinen Modell-ID gpt-image-2.5-sunburst, die ein anderes Schema und eine andere Preisgestaltung hat.

Warum gibt meine Anfrage eine Task-ID statt direkt ein Bild zurück? Jedes Bildmodell auf hiapi läuft über dieselbe asynchrone Task-API (POST /v1/tasks → Polling oder Callback → output[0].url), unabhängig davon, wie schnell das zugrunde liegende Modell tatsächlich ist. Bauen Sie die Integration einmal um dieses Muster herum, funktioniert jedes Modell, das Sie später einsetzen, auf dieselbe Weise.

Was passiert, wenn ich die Ausgabe-URL nicht rechtzeitig herunterlade? Sie läuft ab – das Feld expireAt in der Task-Antwort ist der Unix-Zeitstempel, ab dem die temporäre URL nicht mehr funktioniert. Sobald status success ist, laden Sie die Bytes sofort selbst herunter und speichern Sie sie.

Kann ich mit diesem Modell Bild-zu-Bild-Bearbeitung durchführen? Auf der Route /text-to-image nicht. Für die Bildbearbeitung verwenden Sie die reine Modell-ID gpt-image-2.5-sunburst und übergeben das Eingabefeld image_urls – sehen Sie sich für das exakte Schema die Modellseite an.

Möchten Sie es selbst ausprobieren? Holen Sie sich einen API-Key aus der hiapi-Konsole und ersetzen Sie einfach den Prompt im obigen Python-Beispiel.