So rufen Sie gpt-image-2.5-sunburst/text-to-image über die HiAPI-API auf: curl und Python

Was Ihnen dieser Modell-Endpunkt bietet

gpt-image-2.5-sunburst/text-to-image ist ein Bildgenerierungsmodell, das über die einheitliche HiAPI-API bereitgestellt wird. Sie rufen es über die Modell-ID auf, senden den Prompt in einem Anfragekörper in der Form von chat-completions – genau wie bei Textmodellen – und erhalten in der Antwort die generierten Bilddaten.

Die praktische Auswirkung: Wenn Ihre Codebasis bereits Text über HiAPI verarbeitet, benötigen Sie kein zweites SDK, kein separates Authentifizierungsschema und keine neue Endpunkt-Familie. Es ändert sich nur die Modell-ID.

Wählen Sie diesen Endpunkt, wenn Ihre Aufgabe die Generierung von Bildern aus Prompts ist – also neue Bilder auf Basis einer Textbeschreibung, optional gesteuert durch ein in der Anfrage bereitgestelltes Referenzbild. Wenn Sie vorhandene Bilder analysieren oder beschreiben möchten, anstatt Bilder zu erzeugen, ist ein vision-fähiges Chat-Modell besser geeignet; überlassen Sie die Bildgenerierung diesem Endpunkt und das Bildverstehen einem anderen.

Stellen Sie eine Erwartung vorab ein: Bildaufrufe sind langsamer als Textvervollständigungen. Antwortzeiten im einstelligen Sekundenbereich sind normal; Ihr Client-Timeout sollte an diese Realität angepasst sein und nicht aus einer reinen Textkonfiguration übernommen werden.

Bevor Sie die erste Anfrage senden

Drei Dinge müssen vorbereitet sein.

Ein API-Schlüssel

Erstellen Sie einen Schlüssel in Ihrem HiAPI-Konto und speichern Sie ihn als Umgebungsvariable, nicht im Quellcode:

export HIAPI_API_KEY="your-key-here"

Die exakte Modell-ID

Die Zeichenkette lautet gpt-image-2.5-sunburst/text-to-image. Behandeln Sie sie als undurchsichtigen Bezeichner – kopieren Sie sie, tippen Sie sie nicht aus dem Gedächtnis neu ein. Der Schrägstrich ist Teil der ID. Tippfehler hier sind die häufigste Ursache für fehlgeschlagene erste Aufrufe, und sie erscheinen als Fehler wie „Modell nicht gefunden“, nicht als Nutzlastproblem.

Ein Client, der HTTPS-Anfragen senden kann

Für die erste Validierung genügt curl, das auf den meisten Systemen vorinstalliert ist. Für Anwendungscode reicht Python mit der requests-Bibliothek (oder einem beliebigen HTTP-Client). Dieser Endpunkt erfordert keine spezielle Bildbibliothek im Client; Sie senden JSON und lesen JSON zurück.

Vor dem ersten reinen Textaufruf müssen Sie keine Bilder vorab hochladen oder Speicher konfigurieren. Beginnen Sie mit der minimalen Anfrage unten und fügen Sie Referenzbilder erst hinzu, wenn der grundlegende Roundtrip funktioniert.

Eine minimale funktionsfähige Anfrage mit curl

Dies ist der minimale korrekte Aufruf:

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"
      }
    ]
  }'

Feld für Feld erklärt:

• URL – der standardmäßige HiAPI-chat-completions-Pfad. Bildmodelle verwenden dieselbe Route wie Textmodelle.
• Authorization – Bearer-Token mit dem API-Schlüssel. Wenn dieser Header falsch formatiert ist, erhalten Sie einen 401, bevor das Modell überhaupt aufgerufen wird.
• Content-Type – muss application/json sein.
• model – die exakte Modell-ID aus dem vorherigen Abschnitt.
• messages – ein Standard-Array aus role/content-Objekten. Ihr Prompt ist der content der user-Nachricht.

Bei Erfolg erhalten Sie eine JSON-Antwort mit den generierten Bilddaten sowie den üblichen Completion-Metadaten. Speichern Sie die Rohantwort zunächst in einer Datei und prüfen Sie sie, bevor Sie die Parsing-Logik in Ihr Skript einbauen:

curl -sS ... -o response.json

Sobald dies ein Bild zurückgibt, sind Ihre Anmeldeinformationen und die Nutzlastform korrekt; alle weiteren Probleme sind dann Anwendungslogik, nicht Konfiguration.

Dieselbe Anfrage in Python schreiben

Die Anfragekonvention bleibt gleich – nur Client-Setup, Timeouts und Antwortverarbeitung ändern sich.

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)

Drei Details verdienen Beachtung:

Timeouts sind explizit und asymmetrisch

Das Tupel (10, 180) setzt einen kurzen Verbindungs-Timeout und einen großzügigeren Lese-Timeout. Bildgenerierung dauert nun einmal eine Weile; ein einzelner flacher Timeout, der aus einem Textclient kopiert wurde, erzeugt falsche Fehlschläge. Der Verbindungs-Timeout bleibt kurz, damit Netzwerkprobleme schnell fehlschlagen.

json=payload statt data=

Wenn Sie ein Dictionary über json= übergeben, wird die Serialisierung für Sie erledigt und der Content-Type gesetzt. Wenn Sie eine vorab serialisierte Zeichenkette über data= übergeben, setzen Sie den Header manuell.

Defensives Parsen

Die Antwort ist JSON; protokollieren Sie bei unerwarteten Formen den gesamten Antwortkörper, bevor Sie darauf zugreifen. Gehen Sie vor dem Sehen einer echten Antwort nicht von einer festen Verschachtelungstiefe aus – und nehmen Sie bei einem Nicht-2xx-Status niemals eine Erfolgsform an.

Wenn Sie eine für HiAPI konfigurierte Client-Bibliothek bevorzugen, wird dieselbe Nutzlast gesendet; nur die Aufrufstelle ändert sich.

Referenzbilder korrekt übergeben

Referenzbilder sollten innerhalb des Nachrichteninhalts bereitgestellt werden, nicht als temporäres Feld auf oberster Ebene. Dies ist der Teil der Integration, der am leichtesten subtil schiefgeht, weil fehlerhafte Referenzen oft keinen Fehler auslösen – die Anfrage gelingt einfach, und die Ausgabe ignoriert Ihr Bild.

Halten Sie die Nutzlaststruktur sprachübergreifend konsistent: Die user-Nachricht trägt ein Inhaltsarray, in dem der Textteil den Prompt enthält und der Bildteil die Referenzdaten. Derselbe JSON-Anfragekörper, den Sie in Python erstellen, muss sich bytegenau in curl ausdrücken lassen; wenn Sie kein curl-Äquivalent zur Python-Nutzlast schreiben können, ist die Struktur bereits abgewichen.

Wenn das Ergebnis Ihr Referenzbild zu ignorieren scheint, prüfen Sie in dieser Reihenfolge:

1. Position. Befindet sich der Bildteil innerhalb von messages[].content oder ist er versehentlich auf die oberste Ebene des Anfragekörpers gerutscht? Das Modell sieht nur, was in den Nachrichten steht.
2. Kodierung. Das Referenzbild wird als kodierte Daten in der Anfrage übertragen. Stellen Sie sicher, dass die Daten vollständig und korrekt formatiert sind und nicht durch manuelles Zusammensetzen oder schlechtes Kopieren und Einfügen abgeschnitten wurden.
3. Prompt-Kopplung. Das Referenzbild leitet die Generierung; es ersetzt nicht die Anweisung. Geben Sie ausdrücklich an, welche Rolle das Bild spielt – Stil, Komposition, Motiv –, statt anzunehmen, das Modell könne es ableiten.
4. Größe. Sehr große Referenzen blähen die Anfrage auf und verlangsamen den Roundtrip. Verkleinern Sie sie vor der Kodierung auf die Größe, die die Aufgabe tatsächlich benötigt.

Eine praktische Debugging-Gewohnheit

Erstellen Sie einmal eine Referenzbild-Nutzlast, speichern Sie den exakten funktionierenden JSON-Anfragekörper und verwenden Sie ihn als festes Beispiel wieder. Wenn spätere Aufrufe anormal werden, vergleichen Sie den aktuellen Anfragekörper per Diff mit dem festen Beispiel. Die meisten Referenzbild-Regressionen sind struktureller Natur, und ein Diff findet sie in Sekunden.

Fehler, Timeouts und Wiederholungsversuche behandeln

Bildendpunkte schlagen anders fehl als Textendpunkte: Sie sind langsamer, daher fallen mehr Aufrufe in das von Timeouts ausgelöste Fenster, und blindes Wiederholen ist teurer, weil die Arbeit schwerer ist.

Client-Fehler von vorübergehenden Fehlern unterscheiden

• 4xx (außer 429) – fehlerhafte Nutzlast, falsche Modell-ID, fehlende Authentifizierung. Dieselbe Anfrage erneut zu senden wird genauso fehlschlagen. Korrigieren Sie die Anfrage.
• 401/403 – Anmeldeinformationsproblem. Prüfen Sie Schlüssel und Format des Authorization-Headers.
• 429 – Ratenbegrenzung. Wiederholen Sie, aber mit Backoff und Jitter statt sofort.
• 5xx und Verbindungsfehler – vorübergehend. Wiederholen Sie.
• Lese-Timeout – mehrdeutig: Die Generierung könnte serverseitig abgeschlossen sein. Behandeln Sie einen Timeout nur dann als wiederholbar, wenn Ihr Workflow mögliche Duplikate tolerieren kann.

Nur sichere Inhalte wiederholen

Verwenden Sie exponentielles Backoff mit Jitter und setzen Sie eine kleine Obergrenze für Versuche – drei sind normalerweise ausreichend. Ein einfaches Muster:

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())

Wiederholen Sie innerhalb dieser Schleife keine 4xx-Nutzlastfehler – legen Sie sie sofort offen, damit fehlerhafte Anfragen laut fehlschlagen, statt Versuche zu verschwenden.

Timeouts auf das Modell abstimmen

Der Lese-Timeout für Bildaufrufe sollte ein Vielfaches des Text-Standardwerts betragen und pro Aufruf statt global gesetzt werden, damit Textverkehr nicht darunter leidet. Wenn Ihre Plattform harte Anfrageobergrenzen hat, halten Sie Generierungs-Prompts und Referenzbilder innerhalb eines Budgets, das Sie tatsächlich bewältigen können.

Produktions-Checkliste vor dem Release

Eine kurze Checkliste, die die meisten Vorfälle verhindert:

• Modell-ID an einer Stelle. Definieren Sie gpt-image-2.5-sunburst/text-to-image als Konstante oder Konfigurationswert, nicht als verstreute Zeichenkettenliterale.
• Schlüssel aus Umgebungsvariablen, niemals eingecheckt. Rotieren Sie ihn wie jedes andere Geheimnis.
• Explizite Timeouts mit großzügigem Lesefenster, gesetzt an der Anfrage statt an den Session-Standardwerten.
• Wiederholen Sie nur bei 429/5xx/Timeout, mit Backoff und Jitter und begrenzten Versuchen.
• Bei Fehlern die vollständige Antwort protokollieren – Status, Antwortkörper und Request-ID vor dem Parsen erfassen, damit der Support-Dialog mit Belegen beginnt.
• Funktionierende Nutzlast-Beispiele speichern, die den Normalfall und den Referenzbild-Fall abdecken, um bei Verhaltensänderungen Diffs zu verwenden.
• Referenzbilder im Nachrichteninhalt, aufgabengerecht verkleinert und mit im Prompt beschriebener Rolle.
• Smoke-Test in der CI, der einen echten Aufruf gegen die Modell-ID ausführt, damit umbenannte oder zurückgezogene Modelle vor den Nutzern auffallen.

Keine dieser Gewohnheiten ist spezifisch für die Bildgenerierung, aber jede zielt auf Fehlermuster, die bei Bildaufrufen häufiger auftreten als bei Textaufrufen. Richten Sie sie einmal ein, und der Endpunkt verhält sich wie jeder andere Teil Ihres Stacks. Zu den aktuellen Parametern und Einschränkungen des Modells schauen Sie vor dem Festlegen der Konfiguration auf der Modellseite von HiAPI nach.