So rufen Sie gpt-image-2/text-to-image@ext über die HiAPI-API auf: curl und Python

Was gpt-image-2/text-to-image@ext für Sie bereitstellt

gpt-image-2/text-to-image@ext ist ein Text-zu-Bild-Modell, das über die einheitliche HiAPI-Schnittstelle bereitgestellt wird. Sie senden lediglich einen Prompt sowie optionale Generierungsparameter an denselben Endpunkt und erhalten die generierten Bilddaten zurück. Es ist keine Installation modellspezifischer Komponenten erforderlich, kein separates SDK pro Anbieter anzubinden und kein eigenes Konto zu verwalten – derselbe API-Key und dieselbe Request-Struktur decken die übrigen Funktionen der Plattform ab.

Wählen Sie dieses Modell, wenn Ihr Produkt Textbeschreibungen in neue Bilder verwandeln soll: Marketingtexte in Key Visuals, Nutzer-Prompts in Thumbnails, Design-Tools, die Konzeptbilder auf Abruf rendern. Da der Aufruf eine gewöhnliche HTTP-Anfrage ist, lässt er sich mühelos in Backend-Dienste, Queue-Worker oder Skripte einbetten, ohne dass eine Client-Bibliothek eingebunden werden muss.

Es ist die richtige Wahl, wenn die Eingabe Text und die Ausgabe eine Bitmap ist, die Sie selbst speichern und verteilen möchten. Sollten Sie später auf der Plattform zu einem anderen Bildpfad wechseln, bleibt die Integrationslogik – Authentifizierung, Request-Envelope, Ausgabeverarbeitung – unverändert; nur der Modellbezeichner und der Parameterblock ändern sich.

Wie Sie diese Anleitung lesen

Diese Übung baut sich schichtweise auf. Zuerst eine minimale Anfrage, die ein Bild zurückgibt, dann die Python-Version, anschließend die strukturelle Entscheidung zwischen einmaligem Aufruf und asynchronem Polling und schließlich die Ausgabeverarbeitung. Jede Schicht ist unabhängig testbar, sodass Sie bei Problemen genau wissen, welche Änderung sie eingeführt hat.

Voraussetzungen und Authentifizierung

Bevor Sie die erste Anfrage senden, benötigen Sie zwei Dinge: ein HiAPI-Konto und einen damit verknüpften API-Key. Erstellen Sie den Key im Konto-Dashboard und speichern Sie ihn so, wie Sie jeden Schlüssel aufbewahren würden – lokal in einer Umgebungsvariable, in der Produktion in einem Secrets Manager. Committen Sie ihn nicht ins Repository und fügen Sie ihn nicht in Client-Code ein, der an den Browser ausgeliefert wird.

Die Authentifizierung erfolgt über einen Bearer-Token im Request-Header. Das Format ist immer dasselbe:

Authorization: Bearer $HIAPI_API_KEY

Setzen Sie diese Variable einmal in der Shell; die folgenden Beispiele können sie referenzieren, ohne den Schlüssel auszugeben:

export HIAPI_API_KEY="your-key-here"

Was Sie vor dem Start klären sollten

• Der Key ist aktiv und besitzt Zugriff auf die Bildgenerierung.
• Ihre Umgebung kann ausgehende HTTPS-Anfragen an den HiAPI-Endpunkt senden.
• Sie wissen, wohin die generierten Dateien geschrieben werden – lokales Verzeichnis zum Testen, Objektspeicher in der Produktion.

Fehlt der Key oder ist er falsch formatiert, zeigt sich das Problem sofort beim ersten Aufruf als Authentifizierungsfehler – der früheste und klarste Zeitpunkt, um es zu entdecken.

Eine lauffähige minimale curl-Anfrage

Beginnen Sie mit der minimalen Anfrage, die ein Bild erzeugt. Alles außer dem Prompt ist optional, und den ersten Aufruf schlank zu halten bedeutet, dass ein Fehler mit hoher Wahrscheinlichkeit an der Authentifizierung oder der Request-Struktur liegt und nicht an Parameterkonflikten.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image@ext",
    "prompt": "Eine fleckige Messingkompass auf einer gefalteten Papierkarte, weiches Fensterlicht, geringe Schärfentiefe",
    "size": "1024x1024",
    "n": 1
  }'

Feld für Feld erklärt

• model – der Modellbezeichner. Dies ist der einzige Wert, der die Anfrage an gpt-image-2/text-to-image@ext bindet; er muss exakt stimmen.
• prompt – die Inhaltsbeschreibung. Seien Sie konkret bei Motiv, Stil und Beleuchtung; vage Prompts erzeugen vage Bilder und sind schwerer zu debuggen als Parameterfehler.
• size – die Ausgabegröße. Kann in der Validierungsphase der Pipeline weggelassen werden; der Standardwert wird akzeptiert.
• n – die Anzahl der pro Aufruf generierten Bilder. Halten Sie ihn während der Integration bei 1, damit ein Fehlschlag genau einer Ausgabe entspricht.

Schreiben Sie die Antwort in eine Datei, damit Sie sie prüfen können, ohne dass Binärdaten das Terminal durcheinanderbringen:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json -o response.json

Sobald es ein Bild zurückgibt, haben Sie eine nachweislich funktionierende Basislinie. Jede spätere Änderung sollte eine einzelne, rückrollbare Bearbeitung relativ dazu sein.

Die Anfrage nach Python portieren

Die Python-Version ist dieselbe Anfrage, nur anders übertragen. Verwenden Sie requests – es ist die am wenigsten fehleranfällige Wahl und entspricht eins zu eins den curl-Feldern, die Sie bereits validiert haben.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-image-2/text-to-image@ext",
    "prompt": "Eine fleckige Messingkompass auf einer gefalteten Papierkarte, weiches Fensterlicht",
    "size": "1024x1024",
    "n": 1,
}

response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

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

Die wichtigsten Punkte verstanden

• json=payload setzt den Content-Type und serialisiert den Request-Body in einem Schritt – kein manuelles Zusammenbauen von Strings, keine Escaping-Bugs.
• timeout ist in der Praxis keine Option. Die Bildgenerierung ist langsamer als ein typischer JSON-API-Aufruf; ohne Timeout hängt ein Worker, wenn das Upstream langsam wird.
• raise_for_status() verwandelt HTTP-Fehler in Ausnahmen, die Sie abfangen und klassifizieren können, statt einen fehlerhaften Response-Body weiterfließen zu lassen.

Halten Sie das Payload als dict und nicht als inline-String. Wenn Sie später Parameter hinzufügen, fügen Sie einfach Schlüssel hinzu – die Request-Struktur bleibt gleich, und Sie müssen niemals die Transportschicht erneut debuggen.

Wenn Sie einen SDK-artigen Client bevorzugen, gelten derselbe Endpunkt und dieselben Header weiterhin; nur die Aufrufsyntax unterscheidet sich. Validieren Sie zuerst mit curl und übernehmen Sie dann den Client, auf den Ihre Anwendung standardisiert ist.

Zwischen einmaligem Aufruf und asynchronem Polling wählen

Dies ist eine Design- und keine Syntaxentscheidung, und sie wirkt sich stärker auf die Retry- und Speicherlogik aus als jede andere Wahl in der Integration.

Einmaliger Aufruf

Verwenden Sie einen einmaligen Request-Response-Zyklus, wenn:

• Sie auf Abruf generieren und ein Nutzer wartet.
• Ihre HTTP-Schicht lange Verbindungen toleriert.
• Sie ein Bild pro Aufruf statt im Batch generieren.

Setzen Sie das Timeout großzügig relativ zu der langsamsten Generierungszeit, die Sie beobachtet haben, und behandeln Sie den Timeout als wiederholbaren Fehler, nicht als harten Fehler.

Asynchrones Polling

Wählen Sie asynchron bei Batch-Verarbeitung, wenn Anfragen von Queue-Workern kommen oder der Aufrufer nicht blockieren darf. Das Muster lautet: übermitteln, Handle erhalten, dann den Abschlussstatus abfragen.

import time

def poll_until_done(fetch_status, handle, interval=2, max_wait=300):
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        status = fetch_status(handle)
        if status["state"] == "succeeded":
            return status
        if status["state"] == "failed":
            raise RuntimeError(status.get("error", "generation failed"))
        time.sleep(interval)
    raise TimeoutError("generation did not finish in time")

Regeln für zuverlässig funktionierende Polling-Schleifen

• Backoff. Beginnen Sie mit einem kurzen Intervall und erhöhen Sie es schrittweise; konstantes dichtes Polling verschwendet Kontingent und Rate-Budget.
• Wartezeit begrenzen. Eine max_wait-Deadline verhindert, dass verwaiste Aufgaben einen Worker dauerhaft belegen.
• Handles persistieren. Wenn ein Worker neu startet, müssen Sie das Polling fortsetzen können, statt erneut zu übermitteln und eine doppelte Generierung zu bezahlen.
• Fehlschläge als Endzustand pro Aufgabe behandeln. Der Status failed sollte protokolliert und nicht in einer dichten Schleife stillschweigend wiederholt werden.

Entscheiden Sie früh. Asynchrone Semantik nachträglich in einen synchronen Codepfad einzubauen bedeutet, Aufrufer, Speicherung und Fehlerbehandlung gleichzeitig neu zu schreiben.

Die Bildausgabe verarbeiten

Die Antwort enthält Ihr generiertes Bild, aber es sind Daten innerhalb eines JSON-Envelopes – keine hotlinkbare URL. Behandeln Sie es als Binärausgabe, die Ihnen gehört.

Dekodieren und persistieren

import base64

item = data["data"][0]
image_bytes = base64.b64decode(item["b64_json"])

with open("out.png", "wb") as f:
    f.write(image_bytes)

Wenn die Antwort eine URL statt Inline-Daten enthält, rufen Sie sie sofort ab und schreiben Sie die Bytes in Ihren eigenen Speicher. Generierte URLs sind temporär; alles, was Sie Nutzern bereitstellen, sollte hinter Ihrer eigenen Infrastruktur liegen.

Vor der Verteilung validieren

• Magic Bytes prüfen. PNG beginnt mit \x89PNG; eine HTML-Fehlerseite nicht. Eine Prüfung auf wenige Bytes fängt Proxy-Probleme ab, die HTTP 200, aber einen falschen Response-Body liefern.
• Größe protokollieren. Zeichnen Sie die Bytelänge auf, damit abgeschnittene Downloads im Monitoring sichtbar werden.
• Deterministisch speichern. Benennen Sie Dateien nach der Generierungs-ID statt nach dem Prompt-Text und speichern Sie Prompt, Parameter und Response-Metadaten zusammen mit dem Bild. Diese Kombination erlaubt es Ihnen, jede Ausgabe später zu reproduzieren oder zu auditieren.
• Content-Type korrekt setzen – abgeleitet aus der tatsächlichen Datei, nicht aus einer Annahme.

Metadaten zusammen mit dem Artefakt aufbewahren

Schreiben Sie einen kleinen Begleitdatensatz: Modellbezeichner, vollständiger Prompt, Größe und Anzahl, Zeitstempel sowie jede Request-ID aus der Antwort. Wenn jemand in sechs Monaten fragt, warum dieses Bild so aussieht, ist dieser Datensatz Ihre einzige Antwort.

Häufige Fehler debuggen

Die meisten Erstintegrationsfehler fallen in drei Kategorien. Prüfen Sie in dieser Reihenfolge – die Diagnosekosten steigen ungefähr von niedrig nach hoch.

Authentifizierungsfehler

401 oder 403 bedeutet, der Key ist falsch, wurde widerrufen oder nicht gesendet. Geben Sie die Header-Konstruktion ohne den Schlüssel aus, bestätigen Sie, dass das Präfix Bearer und das Leerzeichen intakt sind, und vergewissern Sie sich, dass die Umgebungsvariable im Prozess, der die Anfrage sendet, tatsächlich gefüllt ist – eine häufige Falle ist, sie in der Shell zu setzen, aber nicht im Worker oder Container.

Fehlerhafter Request-Body

400 deutet meist auf den Request-Body hin. Gehen Sie auf die minimale Anfrage aus dem curl-Abschnitt zurück und fügen Sie Felder eines nach dem anderen wieder hinzu. Häufige Übeltäter:

• Der model-String stimmt nicht exakt mit gpt-image-2/text-to-image@ext überein.
• Der Request-Body ist kein gültiges JSON – überzählige Kommas oder nicht escapte Anführungszeichen.
• Falscher Parametertyp; n ist eine Zahl, kein String.
• Content-Type: application/json fehlt, sodass der Server den Request-Body nicht parsen kann.

Timeouts und langsame Antworten

Wenn die Verbindung abbricht, bevor das Bild zurückkommt, haben Sie wahrscheinlich das Client-Timeout überschritten und keinen Modellfehler. Bei einem Design mit einmaligem Aufruf erhöhen Sie das Timeout; bei jeder Batch-Form wechseln Sie zu asynchronem Polling. Stellen Sie beim Wiederholen sicher, dass keine doppelte Generierung entsteht: Wenn eine Anfrage möglicherweise bereits erfolgreich war, prüfen Sie vor dem erneuten Übermitteln, ob bereits ein Ergebnis vorliegt.

Wenn nichts davon zutrifft

Erfassen Sie die vollständige Antwort der fehlgeschlagenen Anfrage – Statuscode, Header und Body – und reproduzieren Sie sie mit einem minimalen curl-Befehl. Ein Fehler, der bei der minimalen Anfrage weiterhin besteht, ist ein Integrationsproblem Ihrer Umgebung; ein Fehler, der verschwindet, deutet auf die von Ihnen hinzugefügten Parameter hin.