Blog

Tutorial

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

Authentifizierung, Anfragestruktur, ausführbare curl- und Python-Beispiele sowie Fehlerbehebung

Nov 10, 2026
Titelbild: flache facettierte Mineralschnittfläche in Petrol und Malachit auf tiefem Petrol, wie eine gedruckte Edelsteinkunde-Tafel.
Auf dieser Seite

So sieht die Integration Ende-zu-Ende aus

Jeder Text-zu-Bild-Aufruf auf HiAPI folgt demselben Lebenszyklus, und es lohnt sich, diesen zu verstehen, bevor man eine Zeile Code schreibt. Ihre Anwendung erstellt eine JSON-Anfrage, die das Zielbild beschreibt, sendet sie zusammen mit den API-Anmeldedaten an den HiAPI-Endpunkt für gpt-image-2.6-sunburst/text-to-image und erhält eine Antwort mit den generierten Bilddaten oder einer abrufbaren URL. Wenn Sie diese drei Phasen verstanden haben, sind die restlichen Teile dieses Leitfadens nur noch Details.

Die Phasen im Einzelnen:

  1. Authentifizierung – Hängen Sie Ihren HiAPI-API-Schlüssel an die Anfrage an, in der Regel als HTTP-Header. Es ist keine Token-Aushandlung pro Aufruf erforderlich.
  2. Anfrageaufbau – Stellen Sie einen JSON-Anfragetext zusammen, der Ihren Prompt und optional Parameter wie Größe und Anzahl der Bilder enthält.
  3. Übertragung – Senden Sie den Anfragetext per POST an den Endpunkt. Der Aufruf ist synchron, der Client wartet also, bis die Bildgenerierung abgeschlossen ist.
  4. Antwortverarbeitung – Die API gibt strukturiertes JSON zurück. Je nach Endpunktkonfiguration kommen die Bilddaten als URL oder als codierter Bildinhalt an, den Sie decodieren und auf die Festplatte schreiben müssen.

Ein Detail, auf das Sie früh achten sollten: Die Modellkennung gpt-image-2.6-sunburst/text-to-image enthält einen Schrägstrich. Behandeln Sie sie als undurchsichtige Zeichenkette. Versuchen Sie nicht, sie in Anbietername und Modellname aufzuteilen, und führen Sie auch keine eigene URL-Codierung oder Normalisierung durch. Kopieren Sie sie genau so, wie sie in der Dokumentation steht, und platzieren Sie sie an einer Stelle im Code, damit Sie sie später nicht mühsam suchen müssen.

Die folgenden Abschnitte gehen die einzelnen Phasen der Reihe nach durch. Die curl- und Python-Abschnitte verwenden bewusst dieselbe Anfrage-Nutzlast, damit Sie sie Zeile für Zeile vergleichen können; der Abschnitt zur Fehlerbehebung ordnet die wahrscheinlichsten Fehler dem jeweiligen Anfragefeld zu, das Sie korrigieren müssen.

HiAPI-Anfragen authentifizieren

HiAPI verwendet ein API-Schlüssel-basiertes Authentifizierungsschema. Sie beziehen den Schlüssel aus dem Konto-Dashboard und senden ihn bei jeder Anfrage mit. Die Standardform ist ein HTTP-Header an der Anfrage:

Authorization: Bearer YOUR_API_KEY

Manche Clients senden den Schlüssel lieber in einem dedizierten Header, aber sofern Ihre Kontodokumentation nichts anderes angibt, sollten Sie die Form Authorization: Bearer verwenden, da sie mit den meisten HTTP-Tools out of the box funktioniert.

Den Schlüssel aus dem Quellcode heraushalten

Der häufigste Sicherheitsfehler bei der ersten Integration besteht darin, den Schlüssel fest in ein Skript einzubauen und dieses zu committen. Vermeiden Sie das von Anfang an:

  • Lesen Sie den Schlüssel aus einer Umgebungsvariable, z. B. HIAPI_API_KEY, und schlagen Sie beim Start sofort fehl, wenn die Variable fehlt.
  • Fügen Sie eine lokale .env-Datei in .gitignore ein, bevor Sie sie erstellen.
  • In CI- oder Produktionsumgebungen injizieren Sie den Schlüssel aus dem Secret Store der Plattform, statt ihn aus einer committeten Datei zu lesen.

Eine kleine Hilfsfunktion, die den Schlüssel einmal liest und bei Fehlen einen klaren Fehler auslöst, erspart Ihnen später eine verwirrende Debugging-Sitzung:

import os

api_key = os.environ.get("HIAPI_API_KEY")
if not api_key:
    raise RuntimeError("HIAPI_API_KEY is not set")

Den Schlüssel auch bei der Anfrage als Geheimnis behandeln

Widerstehen Sie beim Debuggen fehlgeschlagener Aufrufe der Versuchung, das vollständige Anfrageobjekt inklusive Header auszugeben. Protokollieren Sie stattdessen Endpunkt, Modellkennung und Statuscode. Wenn Sie Header zum Debuggen erfassen müssen, maskieren Sie zuvor den Wert von Authorization. Ein Schlüssel, der in einen Log-Aggregator gelangt, ist genauso exponiert wie ein in ein Repository committeter Schlüssel.

Wenn Sie einen Schlüssel rotieren, wird der alte Schlüssel nach Abschluss der Rotation sofort ungültig. Planen Sie Rotationen daher als regelmäßige Aufgabe und nicht als Notfallmaßnahme.

Der Aufbau einer Text-zu-Bild-Anfrage

Der Anfragetext ist ein JSON-Objekt. Für gpt-image-2.6-sunburst/text-to-image ist die Anzahl der Kernfelder gering – genau deshalb lohnt es sich, die Rolle jedes Feldes genau zu verstehen, statt die Nutzlast blind zu kopieren.

Das Feld model

"model": "gpt-image-2.6-sunburst/text-to-image"

Dieses Feld wählt das Modell aus und ist erforderlich. Die Zeichenkette muss bytegenau mit der Dokumentationskennung übereinstimmen. Ein fehlender Schrägstrich, ein zusätzliches Leerzeichen oder eine geänderte Groß-/Kleinschreibung führt dazu, dass die Anfrage wegen eines unbekannten Modells abgelehnt wird.

Das Feld prompt

"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus"

Dies ist die natürlichsprachliche Beschreibung des Bildes und erforderlich. Praktische Hinweise zum Prompt selbst:

  • Beschreiben Sie zuerst das Motiv, dann die Szene und schließlich Stil- oder Licht Hinweise.
  • Bevorzugen Sie konkrete Substantive gegenüber abstrakten Begriffen; „eine rote Keramiktasse auf einem Holztisch“ ist besser als „eine schöne Tassenszene“.
  • Wenn Sie über mehrere Aufrufe hinweg konsistente Ausgaben benötigen, halten Sie die Formulierung der unveränderlichen Teile stabil und ersetzen Sie nur die variablen Teile programmatisch.

Optionale Parameter

Je nach Endpunkt können Sie zusätzlich Parameter senden, die Form und Anzahl der Ausgaben steuern. Die häufigsten sind:

  • size – die Ausgabegröße im dokumentierten Format, z. B. 1024x1024. Wird der Parameter weggelassen, gilt der Standardwert; bei einem nicht unterstützten Wert ist mit einem Validierungsfehler zu rechnen.
  • n – die Anzahl der für einen Prompt generierten Bilder. Jedes generierte Bild wird separat abgerechnet, halten Sie den Wert daher so niedrig wie für Ihren Workflow nötig.

Senden Sie nur die Parameter, die Sie tatsächlich benötigen. Unbekannte Felder können strenge Validierungsfehler auslösen, und der Fehler verweist dann auf ein Feld, das Sie gar nicht senden wollten.

Ein vollständiges Beispiel für den Anfragetext

{
  "model": "gpt-image-2.6-sunburst/text-to-image",
  "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
  "size": "1024x1024",
  "n": 1
}

Das ist die gesamte Vereinbarung. Alles Weitere in diesem Leitfaden dreht sich um die Übertragung dieser Nutzlast, die Fehlerbehandlung und die Lebenszyklusverwaltung.

Eine funktionierende Anfrage mit curl senden

Bevor Sie einen Python-Client bauen, bestätigen Sie mit curl, dass Endpunkt und Anmeldedaten funktionieren. So lassen sich Authentifizierungsprobleme von Codeproblemen trennen.

Der Aufrufbefehl

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst/text-to-image",
    "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
    "size": "1024x1024",
    "n": 1
  }'

Einige Hinweise zu diesen Flags:

  • -sS hält die Ausgabe sauber und zeigt dennoch Übertragungsfehler an.
  • -X POST gibt die Methode an; der Anfragetext wird über -d übergeben.
  • Die einfachen Anführungszeichen um den JSON-Anfragetext verhindern, dass die Shell ihn zerstört. In der Windows-cmd gelten andere Regeln für JSON-Anführungszeichen; verwenden Sie dort curl.exe mit doppelten Anführungszeichen und escapten inneren Anführungszeichen oder führen Sie den Aufruf aus einem Shell-Skript oder Python aus.

Wenn Sie den genauen Endpunktpfad aus Ihrer Kontodokumentation verwenden, ersetzen Sie ihn hier; die Form der Anfrage ändert sich dadurch nicht.

Die Rohantwort prüfen

Wenn etwas schiefgeht, benötigen Sie den Statuscode und den Antworttext. Fügen Sie -i hinzu, um die Antwortheader einzuschließen, oder -w "\nHTTP %{http_code}\n", um den Status am Ende auszugeben:

curl -sS -o response.json -w "HTTP %{http_code}\n" -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

Es lohnt sich, die Nutzlast in payload.json zu speichern und über @payload.json zu referenzieren: Sie vermeiden Fehler durch Shell-Quoting und können den Prompt bearbeiten, ohne den Befehl neu zu schreiben. Wenn der Prompt vertraulichen Text enthält, halten Sie die Datei aus der Versionskontrolle heraus.

Denselben Aufruf mit Python ausführen

Die Python-Version hält den JSON-Anfragetext bytegenau identisch. Nur der Transport ändert sich. Die Verwendung von requests fügt eine Abhängigkeit hinzu, hält den Code aber lesbar; für alles, was über ein Einwegskript hinausgeht, lohnt sich die Installation.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-image-2.6-sunburst/text-to-image",
    "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
    "size": "1024x1024",
    "n": 1,
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.hiapi.ai/v1/images/generations",
    headers=headers,
    json=payload,
    timeout=120,
)

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

Warum json=payload statt data=json.dumps(payload): Wenn Sie ein dict an das Schlüsselwortargument json übergeben, wird es serialisiert und der Content-Type-Header automatisch gesetzt. Eine Zeichenkette an data zu übergeben funktioniert ebenfalls, aber man vergisst leicht, den Header zu setzen, was sich später als verwirrender Validierungsfehler zeigt.

Wenn Sie lieber die Standardbibliothek verwenden

Um Abhängigkeiten zu vermeiden, können Sie urllib.request aus der Standardbibliothek nutzen. Das Payload-Dictionary bleibt unverändert:

import json, os, urllib.request

payload = {
    "model": "gpt-image-2.6-sunburst/text-to-image",
    "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
}

request = urllib.request.Request(
    "https://api.hiapi.ai/v1/images/generations",
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode("utf-8"),
)

with urllib.request.urlopen(request, timeout=120) as response:
    data = json.loads(response.read().decode("utf-8"))

So oder so: Die Bildgenerierung dauert länger als ein typischer JSON-API-Aufruf. Setzen Sie die Timeouts großzügig, sonst laufen Sie bei einer Anfrage in einen Timeout, die kurz vor dem Erfolg steht, und zahlen beim erneuten Versuch doppelt dafür.

Die Antwort verarbeiten und das Bild speichern

Eine erfolgreiche Antwort ist JSON. Die Bildausgabe kommt üblicherweise als URL (die Sie separat abrufen müssen) oder als codierter Bildinhalt in der Nutzlast an. Prüfen Sie in der Endpunktdokumentation, welche Form gilt, und behandeln Sie beide Formen defensiv, da die genaue Form je nach Parametern variieren kann.

Die Antwortstruktur lesen

Die Antwort ist ein JSON-Objekt mit der generierten Ausgabe und Metadaten. Untersuchen Sie es einmal interaktiv, bevor Sie Parsing-Code schreiben:

print(json.dumps(data, indent=2)[:2000])

Finden Sie heraus, wo das Bild liegt. Wenn Sie ein URL-Feld sehen, laden Sie es herunter. Wenn Sie base64-Inhalt sehen, decodieren Sie ihn. Gehen Sie nicht davon aus, dass eine URL dauerhaft gültig ist – behandeln Sie sie als kurzlebig und kopieren Sie die Bytes sofort in Ihren eigenen Speicher.

URL-basierte Ergebnisse speichern

image_url = data["data"][0]["url"]
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

Codierte Ergebnisse speichern

import base64

encoded = data["data"][0].get("b64_json") or data["data"][0].get("image")
if encoded:
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(encoded))

Verwenden Sie in echten Arbeitslasten für jeden Aufruf einen anderen Dateinamen – Zeitstempel, Anfrage-ID oder ein aus dem Prompt abgeleiteter Slug. Wenn Sie Ausgaben später neu generieren oder auditieren möchten, speichern Sie den Prompt zusammen mit dem Bild in einer Sidecar-JSON-Datei.

Erfolgsantworten an einer Stelle behandeln

Kapseln Sie das Parsen der Antwort in einer Funktion, die eine Liste von Byte-Strings zurückgibt, einen pro Bild. So müssen Aufrufer nur die Bytes schreiben oder hochladen und nicht wissen, ob sie aus einer URL oder aus codiertem Inhalt stammen. Wenn Sie später das Modell wechseln, zahlt sich diese Abstraktion aus.

Häufige Fehler diagnostizieren

Die meisten Fehler bei der ersten Integration fallen in wenige Kategorien. Ordnen Sie Statuscode und Meldung der jeweiligen Lösung unten zu, bevor Sie irgendetwas anderes ändern.

Authentifizierungsfehler

Wird die Anfrage wegen fehlender oder ungültiger Anmeldedaten abgelehnt, fehlt der Authorization-Header, ist er falsch formatiert oder enthält einen widerrufenen Schlüssel. Prüfen Sie in dieser Reihenfolge:

  1. Bestätigen Sie Headername und Wertformat, einschließlich des wörtlichen Bearer gefolgt von einem Leerzeichen.
  2. Bestätigen Sie, dass die Umgebungsvariable in der Shell oder dem Prozess, der den Aufruf ausführt, tatsächlich gesetzt ist – ein in einem Terminal gesetzter Schlüssel existiert nicht in einem anderen.
  3. Bestätigen Sie, dass der Schlüssel beim Kopieren nicht rotiert oder abgeschnitten wurde.

Validierungsfehler im Anfragetext

Die API lehnt Anfragetexte ab, denen Pflichtfelder fehlen oder die ungültige Werte enthalten. Die Meldung nennt in der Regel das problematische Feld:

  • Fehlendes model oder prompt – beide sind erforderlich. Senden Sie sie bei jedem Aufruf explizit, statt sich auf Standardwerte zu verlassen.
  • Unbekanntes Modell – prüfen Sie die Kennung gpt-image-2.6-sunburst/text-to-image erneut, einschließlich Schrägstrich und Groß-/Kleinschreibung. Fügen Sie keine Leerzeichen davor oder dahinter ein.
  • Ungültige Größe – verwenden Sie eine unterstützte Größenzeichenkette im dokumentierten Format. Wenn Sie size bewusst weglassen, entfernen Sie das Feld, anstatt null zu senden.
  • Fehlerhaftes JSON – meist ein Shell-Quoting-Problem in curl oder ein Kodierungsproblem in Python. Validieren Sie vor dem Senden mit json.dumps(payload) und prüfen Sie, was tatsächlich übertragen wird.

Rate Limits und Kontingente

Wenn Sie eine Drosselungsantwort erhalten, versuchen Sie es mit Backoff und Jitter erneut, statt sofort. Wenn die Meldung auf ein Kontingentproblem hinweist, prüfen Sie Tarif und Nutzungsdashboard des Kontos statt des Anfragetexts – die Nutzlast ist wahrscheinlich korrekt.

Serverfehler

5xx-Fehler während der Generierung sind meist vorübergehend. Wiederholen Sie den Aufruf ein- oder zweimal mit exponentiellem Backoff. Wenn er bei unterschiedlichen Prompts und Nutzlasten weiterhin auftritt, liegt das Problem nicht bei Ihnen; erfassen Sie den Antworttext und wenden Sie sich mit Uhrzeit der Anfrage und Modellkennung an den Support.

Fehler beim Content-Type

Eine Anfrage ohne Content-Type: application/json kann verwirrende Validierungsfehler erzeugen, weil der Server die Nutzlast nicht parsen kann. Setzen Sie den Header in curl explizit; lassen Sie ihn in Python vom Parameter json= setzen.

Die Integration produktionsreif machen

Der erste erfolgreiche Aufruf ist der einfache Teil. Die folgenden Anpassungen halten die Integration sowohl bei den Betriebskosten als auch bei Änderungen günstig.

Die Modellkennung konfigurierbar machen

Speichern Sie die Modellkennung in einer Konstante oder einem umgebungsgesteuerten Konfigurationswert und niemals inline an mehreren Aufrufstellen. Wenn Sie später andere Modelle evaluieren, ändern Sie einen Wert und führen die Tests erneut aus. Behalten Sie das Feld pro Anfrage in den Logs, um zu dokumentieren, welches Modell jedes Bild erzeugt hat, damit Sie die Qualität beim Modellwechsel vergleichen können, ohne alles neu laufen zu lassen.

Strategisch wiederholen

Wiederholen Sie Netzwerkfehler, Timeouts und 5xx-Antworten mit exponentiellem Backoff und Jitter. Wiederholen Sie niemals Validierungs- oder Authentifizierungsfehler – die Anfrage scheitert genauso erneut, Sie vergeuden nur Rate Limit. Begrenzen Sie die Versuche und protokollieren Sie für jeden Versuch die Nummer und den endgültigen Status.

Timeouts passend zur Arbeitslast wählen

Bildgenerierung ist langsam. Zu kurze Timeouts lassen eigentlich erfolgreiche Anfragen scheitern, und bei einem erneuten Versuch zahlen Sie möglicherweise für eine bereits abgeschlossene Generierung. Setzen Sie großzügige Timeouts pro Anfrage und behandeln Sie Überschreitungen als Signal, die Latenz zu untersuchen, nicht als Grund für aggressive Wiederholungen.

Den Client schichten

Halten Sie die drei Teile getrennt: einen Payload-Builder, der Anwendungseingaben in ein Anfrage-Dictionary umwandelt; eine Transportfunktion, die den HTTP-Aufruf ausführt; und einen Handler, der die Antwort in Bytes decodiert. Den Builder ohne Netzwerkaufruf zu testen ist sehr einfach; den Transport durch einen Mock zu ersetzen ebenfalls. Diese Schichtung macht außerdem einen Modellwechsel zu einer Änderung in einer Datei statt zu einer Suche im ganzen Codebestand.

Protokollieren, was Sie im Vorfall brauchen

Protokollieren Sie Zeitstempel, Endpunkt, Modellkennung, HTTP-Status, einen Hash oder eine gekürzte Form des Prompts und die Dauer der Anfrage. Protokollieren Sie niemals API-Schlüssel oder vollständige Header. Wenn Sie generierte Bilder speichern, legen Sie den Speicherpfad nach Anfrage-ID fest, damit Support-Tickets zur tatsächlichen Anfrage zurückverfolgt werden können.

Wenn die Authentifizierung über Umgebungsvariablen erfolgt und die Nutzlast in einer Builder-Funktion isoliert ist, lässt sich das hier mit gpt-image-2.6-sunburst/text-to-image geübte Muster direkt auf jedes andere Bildmodell am selben HiAPI-Endpunkt übertragen.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen