Tutorial

So verwendest du die GPT Image 2 API: Leitfaden für Text-zu-Bild und Bild-zu-Bild

Nov 3, 2026

Was die GPT Image 2 API Entwicklern bietet

Die GPT Image 2 API bietet dir eine einheitliche, konsistente Schnittstelle zur Bilderzeugung anhand von Prompts. Du musst nicht mehrere Anbieter zusammenstückeln oder mehrere SDKs pflegen – du sendest einfach eine HTTP-Anfrage an HiAPI.ai und erhältst die Bilddaten zurück. Das ist wichtig, wenn du Funktionen wie Marketing-Asset-Generatoren, Onboarding-Illustrationen oder kreative Werkzeuge für Endnutzer baust, denn Latenz, Verfügbarkeit und eine vorhersehbare Anfragestruktur sind entscheidend.

Du verwendest zwei Generierungsmodi:

Text-zu-Bild: Du gibst einen Prompt und die Zielgröße an, und das Modell erzeugt das Bild von Grund auf.
Bild-zu-Bild: Du gibst einen Prompt plus ein oder mehrere Referenzbilder an, und das Modell erzeugt das Bild unter Anleitung dieser Referenzbilder.

Beide Modi teilen dieselbe Authentifizierung und Antwortstruktur. Sobald du also einen funktionierenden Aufruf hast, ist der zweite nur eine kleine Änderung und keine komplett neue Integration. Dieser Leitfaden behandelt der Reihe nach die Wahl zwischen den beiden Varianten, eine minimale curl-Anfrage, den Umgang mit Referenzbildern, das Anfordern von 4K-Ausgaben, die Portierung nach Python und Fehlerbehandlungsmuster, die stille Fehler in Produktions-Bildpipelines verhindern.

Wenn du irgendeine Funktion baust, die Bilderzeugung über einen stabilen API-Vertrag benötigt, ist der Rest dieses Artikels der kürzeste Weg von null zu einer lauffähigen Anfrage.

Text-zu-Bild vs. Bild-zu-Bild: die Variante wählen

Bevor du Code schreibst, entscheide, welche Variante dein Produkt tatsächlich braucht. Diese Wahl hängt vor allem davon ab, wie viel Kontrolle du über die Ausgabe willst und wie viel Inhalt deine Nutzer voraussichtlich liefern müssen.

Wann du Text-zu-Bild verwendest

Text-zu-Bild ist die passende Standardwahl, wenn:

Nutzer in Text beschreiben, was sie wollen, und kein Quellmaterial haben.
Du Platzhalterbilder, Key Visuals oder Varianten auf Basis fester Prompt-Vorlagen erzeugst.
Du einen möglichst einfachen Request-Body willst – einen Prompt und eine Größe –, um das Anfragevolumen klein und die Latenz vorhersehbar zu halten.

Wann du Bild-zu-Bild verwendest

Bild-zu-Bild ist die richtige Wahl, wenn die Ausgabe eng an bereits vorhandenem Inhalt bleiben muss:

Ein hochgeladenes Produktfoto stilistisch überarbeiten oder neu rendern.
Eine konsistente visuelle Behandlung auf eine Reihe von Referenzmaterialien anwenden.
Komposition, Farbpalette oder Motiv so lenken, dass das Ergebnis zur bestehenden Marke oder Szene passt.

Praktische Regel

Wenn allein der Prompt die Ausgabe vollständig bestimmen kann, verwende Text-zu-Bild. Wenn ein Teil der Absicht im Bild statt im Text steckt – und die Beschreibung per Prompt nachteilig, langwierig oder unzuverlässig wäre –, verwende Bild-zu-Bild und übergib Referenzbilder.

Ein häufiger Fehler ist, auf Bild-zu-Bild auszuweichen, obwohl ein besserer Prompt das Problem lösen würde. Referenzbilder erhöhen den Upload-Aufwand und die Wahrscheinlichkeit, dass die Anfragevalidierung fehlschlägt. Beginne mit Text-zu-Bild und wechsle erst dann zur Referenzbild-Variante, wenn du ein konkretes visuelles Attribut benennen kannst, das ein Prompt nicht erfassen kann.

Stelle deine erste Text-zu-Bild-Anfrage mit curl

Beginne mit curl. Es schließt das Verhalten eines SDK als Variable aus, sodass du bei einem Fehler sicher sein kannst, dass das Problem in der Authentifizierung oder der Request-Body-Struktur liegt und nicht in einer Client-Bibliothek.

Setze zuerst den API-Schlüssel als Umgebungsvariable, damit er nicht in der Shell-Historie oder in der Versionskontrolle landet:

export HIAPI_API_KEY="your_api_key_here"

Sende dann eine minimale Anfrage:

curl -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",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024"
  }'

Was du in der Antwort prüfen solltest:

HTTP-Statuscode.200 bedeutet, dass die Anfrage akzeptiert und verarbeitet wurde. Bei jedem anderen Statuscode lies zuerst den Fehler-Response-Body, bevor du irgendetwas änderst.
Authentifizierung.401 bedeutet fast immer, dass der Schlüssel fehlt, falsch formatiert oder abgelaufen ist – bestätige, dass der Authorization-Header im Format Bearer gefolgt vom Schlüssel vorliegt.
Request-Body.400 deutet meist auf ein bestimmtes Feld hin: ein falsch geschriebener Parameter, ein vom Modell nicht akzeptierter Größenstring oder ein Prompt, der die Validierung nicht besteht.
Bildnutzlast.Je nach Antwortmodus erhältst du eine abrufbare URL oder base64-Bilddaten. Behandle beides, damit dein Client später nicht überrascht wird.

Sobald dieser Aufruf erfolgreich ist, hast du drei Dinge gleichzeitig bestätigt: Der Schlüssel ist gültig, der Endpunktpfad ist korrekt und die JSON-Struktur wird akzeptiert. Jede spätere Änderung in diesem Leitfaden beginnt von dieser bewährten Ausgangsbasis.

Ausgabe mit Referenzbildern lenken

Bild-zu-Bild-Anfragen behalten dieselbe Anfragehülle wie Text-zu-Bild und fügen eine Referenzbild-Eingabe hinzu. Der Prompt trägt weiterhin die Anweisungen – das Referenzbild trägt den visuellen Kontext.

Der Unterschied im Request-Body besteht darin, dass du jetzt zusätzlich zum Prompt Bilddaten lieferst. In der Praxis bedeutet das, entweder eine vom Dienst abrufbare URL oder ein inline base64-kodiertes Bild bereitzustellen, je nachdem, welche Form deine Integration unterstützt. Beachte folgende Regeln:

Prompt und Referenzbild müssen übereinstimmen.Wenn der Prompt ein rotes Produkt beschreibt, das Referenzbild aber blau ist, erhält das Modell widersprüchliche Signale. Formuliere den Prompt als Anweisung zu dem Referenzbild („Zeichne diese Szene im Aquarellstil neu“), nicht als Beschreibung, die dem Referenzbild widerspricht.
Sende nur, was du brauchst.Ein starkes Referenzbild ist meist besser als mehrere schwache. Mehrere Referenzbilder erhöhen das Upload-Volumen und erschweren es festzustellen, welches die Ausgabe gesteuert hat.
Achte auf das Anfragevolumen.base64-kodierte Bilder blähen die Anfragenutzlast erheblich auf. Wenn du große Fotos hochlädst, ist das der erste Ort, den du prüfen solltest, wenn Anfragen langsam werden oder abgelehnt werden.
Validiere vor dem Senden.Prüfe, ob das Bild in einem unterstützten Format vorliegt und sich sauber dekodieren lässt. Fehlerhafte base64-Strings erzeugen schwer verständliche Fehler, deren Diagnose zeitaufwendig ist.

Die nutzbare Anfragestruktur sieht so aus:

curl -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",
    "prompt": "Restyle this scene as a soft watercolor painting, keep composition intact",
    "image": "https://example.com/reference.jpg",
    "size": "1024x1024"
  }'

Da sich die Anfragehülle nicht ändert, bleibt dein zuvor validierter curl-Aufruf das Debug-Werkzeug: Ersetze den Request-Body, behalte die Header bei und vergleiche die Antwort Feld für Feld.

4K-Ausgaben anfordern

Die Ausgaberesolution wird in der Anfrage angegeben, nicht vom Modell angenommen. Wenn du hochauflösende Ausgaben brauchst, gib sie explizit mit dem Parameter size an – verlasse dich nicht darauf, dass der Standardwert groß ist.

{
  "model": "gpt-image-2",
  "prompt": "A detailed isometric illustration of a city block, warm evening light",
  "size": "3840x2160"
}

Beim Wechsel zu höheren Auflösungen solltest du Folgendes prüfen:

Unterstützte Größenstrings.Größenwerte werden gegen den vom Modell akzeptierten Bereich validiert. Abgelehnte Größen geben 400 zurück, statt stillschweigend herabzustufen – bestätige also den exakten Größenstring, den du brauchst, statt einen nahen, aber falschen Wert zu raten.
Antwortvolumen.4K-Bilddaten sind deutlich größer als 1K-Ergebnisse. Wenn deine Antwort base64 oder eine URL enthält, die du sofort herunterlädst, plane dafür Budget in Speicher und Timeout-Einstellungen ein.
Latenz.Die Generierung in höherer Auflösung dauert länger. Setze Client-Timeouts großzügig, statt eine langsame, aber erfolgreiche Anfrage auf deiner Seite in einen Timeout laufen zu lassen.
Kostenmodell.Die Abrechnung richtet sich nach der angeforderten Ausgabegröße und -menge, triff deine Wahl also bewusst: Generiere in der Auflösung, die die Funktion tatsächlich braucht, und downsample in deiner eigenen Pipeline, wenn die UI keine volle Auflösung benötigt. Aktuelle Preise findest du im Preispaneel der Website.
Vorsichtig hochskalieren.Wenn du eine größere Ausgabe brauchst, als das Modell liefert, ist das Hochskalieren nach der Generierung ein separater Schritt mit eigenen Qualitätsabwägungen. Entscheide bewusst, welchen Weg du gehen willst.

Bevor du 4K in Batch-Jobs einsetzt, teste 4K mit einem bewährten Prompt, damit auflösungsbezogene Fehler nicht mit Authentifizierungs- oder Request-Body-Problemen verwechselt werden.

Die Anfrage nach Python portieren

Schreibe die Anfrage in Python nicht von Grund auf neu. Portiere den exakten Request-Body, den du bereits in curl validiert hast, und bestätige dann separat die Antwortbehandlung.

import os
import base64
import requests

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

payload = {
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()

item = data["data"][0]
if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
    with open("output.png", "wb") as f:
        f.write(image_bytes)
else:
    image_url = item["url"]
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)

Hinweise zur Portierung:

Behalte den Schlüssel in einer Umgebungsvariable, genau wie bei curl. Bette ihn niemals inline ein.
Setze explizite Timeouts.Die Bilderzeugung ist langsamer als ein typischer JSON-API-Aufruf; ein kurzer Standard-Timeout ist eine häufige Ursache für falsche Fehlschläge.
Behandle beide Antwortmodi.Die Verzweigung nach b64_json und url lässt den Code unabhängig von der Antwortkonfiguration funktionieren.
Wiederverwendbare Funktion.Kapsele dies in eine kleine Hilfsfunktion generate_image(prompt, size), sodass sich Text-zu-Bild und Bild-zu-Bild nur im optionalen Feld image im Payload unterscheiden.

Da das Payload-Dictionary genau dasselbe Objekt ist, das du in curl getestet hast, stammen alle Verhaltensänderungen, die du in Python beobachtest, praktisch immer von der Client-Seite – Header, Kodierung oder Timeouts –, was den Debugging-Bereich stark eingrenzt.

Fehler behandeln und Antworten validieren

Die Bilderzeugung ist von Natur aus ein fehleranfälliger Aufruf: Sie ist langsamer als die meisten API-Endpunkte, trägt große Nutzlasten und hängt von der Modellverfügbarkeit ab. Behandle sie als Vorgang, der gelegentlich fehlschlägt und wiederholt werden muss, nicht als einmalige Operation.

Checkliste für Antworten

Prüfe den Status vor dem Parsen.Rufe raise_for_status() auf oder prüfe den Statuscode und lies den Fehler-Response-Body – er nennt meist das problematische Feld.
Validiere die Struktur.Bestätige vor dem Indexieren, dass data existiert und nicht leer ist. Gehe nicht davon aus, dass data[0] immer vorhanden ist.
Verifiziere die Bildbytes.Prüfe nach dem Dekodieren, dass die Ausgabe nicht leer ist und mit einer gültigen Bildsignatur beginnt. Eine Datei mit null Bytes ist ein stiller Fehler, der sich erst viel später zeigt.
Protokolliere die Request-ID.Bewahre die Request-Kennung der Antwort in den Logs auf, damit fehlgeschlagene Generierungen nachverfolgt werden können, ohne sie reproduzieren zu müssen.

Retry-Strategie

Wiederhole nur temporäre Fehler.Timeouts, Verbindungsabbrüche und 5xx-Antworten sind es wert, wiederholt zu werden. 401 oder 400 schlagen jedes Mal auf dieselbe Weise fehl – korrigiere die Anfrage, statt sie zu wiederholen.
Verwende exponentielles Backoff mit Jitter.Beginne mit einer kurzen Verzögerung und erhöhe sie schrittweise; Jitter verhindert, dass eine Gruppe von Workern synchron wiederholt.
Begrenze die Anzahl der Versuche.In der Regel reichen zwei bis drei Wiederholungen. Danach gib den Fehler an den Nutzer weiter oder leite die Aufgabe in einen Dead-Letter-Pfad um.
Mache es idempotent.Da Wiederholungen doppelte Generierungen erzeugen können, speichere die Ergebnisse verknüpft mit der ursprünglichen Task-ID, damit Wiederholungen niemals eine für den Nutzer sichtbare Operation doppelt berechnen.

Asynchron gestalten

Hochauflösende Generierungen dauern länger, also halte den Request-Thread nicht dauerhaft besetzt, wenn deine Architektur es erlaubt. Lege die Aufgabe in eine Warteschlange, gib dem Aufrufer eine Task-ID zurück und lass Worker den Aufruf mit der oben beschriebenen Retry-Strategie ausführen. So bleibt deine Web-Schicht reaktionsfähig und die langsame, fehleranfällige Arbeit landet dort, wo Wiederholungen günstig sind.

Baue diese Prüfungen schon ab dem ersten funktionierenden Aufruf ein, nicht erst nach dem ersten Produktionsvorfall – die Kosten einer kleinen Validierungshilfsfunktion sind weit geringer als die Fehlersuche an einer leeren Bilddatei drei Wochen später. Wenn Authentifizierung, Request-Body-Struktur, Auflösung und Retries bestätigt sind, wird die GPT Image 2 API zu einem zuverlässigen Baustein statt zu einer nur für Demos tauglichen Integration.