Blog

Tutorial

So rufen Sie gpt-image-2.6-flare/text-to-image über die HiAPI API auf: curl, Python und lauffähige Anfragen

Nov 10, 2026
Abstraktes Cover-Artwork aus überlappenden, durchscheinenden Glasscheiben, die ein blasses Feld in kühle blaue Bänder verwandeln, matt und architektonisch, ohne Text.
Auf dieser Seite

Was dieses Tutorial aufbaut

Die meisten Text-to-Image-Tutorials enden mit einem Screenshot einer erfolgreichen Antwort. Das reicht nicht aus, um irgendetwas in den Produktivbetrieb zu bringen. Dieses Tutorial führt Sie von Grund auf durch den Aufbau einer wiederverwendbaren, lauffähigen Integration über die einheitliche HiAPI API mit dem Modell gpt-image-2.6-flare/text-to-image.

Am Ende verfügen Sie über drei Dinge:

  • Eine bestätigt funktionierende Anfrage, zunächst als curl-Befehl und dann als äquivalentes Python-Skript.
  • Ein klares mentales Modell davon, wie HiAPI Text-to-Image-Aufrufe strukturiert – Endpunktpfad, Authentifizierungs-Header, Prompt-Nutzlast und Antwortkörper –, sodass Sie die Beispiele an Ihre eigenen Prompts anpassen können, statt sie auswendig zu lernen.
  • Muster, um diesen einzelnen Aufruf zu einem Batch-Betrieb zu erweitern, sowie eine Methode, um zu entscheiden, welche Fehler wiederholt und welche behoben werden sollten.

Wir halten den Code schlank und die Abhängigkeiten minimal. Das Python-Beispiel verwendet nur die Standardbibliothek, sodass Sie es in jeder Umgebung mit installiertem Python ausführen können; sobald Sie mit der Anfragestruktur vertraut sind, passen Sie es an requests oder einen asynchronen Client an. Wenn Sie direkt zum lauffähigen Aufruf springen möchten, gehen Sie zum curl-Abschnitt und kehren Sie später für die Erklärungen zurück.

Voraussetzungen und Anmeldedaten

Bevor Sie den ersten Aufruf tätigen, stellen Sie sicher, dass Sie Folgendes haben:

  1. Ein HiAPI-Konto. Melden Sie sich im Dashboard an, um Anmeldedaten zu erstellen und zu verwalten.
  2. Einen API-Schlüssel. Erstellen Sie einen im Bereich für API-Schlüssel im Dashboard. Behandeln Sie ihn wie ein Passwort: Er autorisiert jede Anfrage, die Ihrem Konto in Rechnung gestellt wird.
  3. Eine Möglichkeit, HTTP-Anfragen zu senden. Entweder eine Shell mit installiertem curl oder Python 3 mit Standardbibliothek (urllib und json sind beide in Python enthalten).

Den Schlüssel über Umgebungsvariablen verwalten

Fügen Sie den Schlüssel niemals direkt in Quelldateien ein, die eingecheckt werden könnten. Exportieren Sie ihn stattdessen in der Shell:

export HIAPI_API_KEY="your-api-key-here"

Verwenden Sie in Windows PowerShell $env:HIAPI_API_KEY = "your-api-key-here". Injizieren Sie ihn in CI als Secret. Laden Sie ihn in lang laufenden Diensten beim Start aus einem Secret-Manager.

Wissen, wo die Basis-URL liegt

HiAPI bietet eine einzige einheitliche API-Oberfläche, sodass die Basis-URL über alle Modelle hinweg stabil bleibt. Halten Sie sie in einem Konfigurationswert – eine Umgebungsvariable eignet sich gut – statt sie im Code zu verstreuen. So erfordert der Wechsel zwischen Staging und Produktion oder das Ausrichten von Tests auf einen Mock-Server nur eine Zeile Änderung.

Der Modellbezeichner, den Sie aufrufen werden, ist gpt-image-2.6-flare/text-to-image. Beachten Sie, dass er einen Schrägstrich enthält; halten Sie den Bezeichner vollständig und platzieren Sie ihn an der Pfadposition, die der Anfrage-Builder erwartet, genau wie in den folgenden Beispielen gezeigt.

Mit exportiertem Schlüssel und notierter Basis-URL können Sie sich nun die Anfrage selbst ansehen.

Anatomie einer Text-to-Image-Anfrage

Jeder HiAPI-Text-to-Image-Aufruf hat dieselben vier Bestandteile. Sobald Sie sie verstehen, wird der Wechsel von Modell oder Prompt mechanisch.

1. Der Endpunktpfad

Die Anfrage verwendet den Modellbezeichner als Teil des Pfads: gpt-image-2.6-flare/text-to-image, angehängt an Ihre Basis-URL. Dies ist die Adresse, die Ihren Aufruf hinter der einheitlichen Schnittstelle an das richtige Modell weiterleitet.

2. Der Authentifizierungs-Header

Die Authentifizierung erfolgt über ein Bearer-Token im Authorization-Header:

Authorization: Bearer $HIAPI_API_KEY

Jede Anfrage muss diesen Header enthalten. Ein fehlender oder falsch formatierter Header ist die häufigste Ursache für einen fehlgeschlagenen ersten Aufruf.

3. Der Anfragekörper

Ein Text-to-Image-Aufruf ist ein POST mit einem JSON-Körper. Im Kern steht der Prompt – die natürlichsprachliche Beschreibung des gewünschten Bildes. Der Körper trägt außerdem die Generierungseinstellungen. Da HiAPI die Anfragestruktur über Modelle hinweg vereinheitlicht, können Sie denselben Anfrage-Builder wiederverwenden und den Modellbezeichner ändern, wenn Sie Ausgaben vergleichen möchten.

4. Der Antwortkörper

Eine erfolgreiche Antwort liefert das generierte Bild (oder eine Referenz darauf) sowie Metadaten zur Generierung. Ihr Client sollte den HTTP-Status prüfen, bevor er versucht, das Bild zu parsen. Behandeln Sie die Antwort als Daten, nicht als etwas zum Anschauen – für die Automatisierung benötigen Sie die Bild-Bytes oder -URL und müssen jede Anfragekennung zusammen mit ihnen speichern, um die Datei dem Aufruf zuordnen zu können, der sie erzeugt hat.

Das ist das gesamte Modell. Alles Weitere ist die konkrete Instanziierung dieser vier Teile.

Eine lauffähige Anfrage mit curl senden

Dies ist der vollständige Aufruf. Ersetzen Sie den Prompt durch Ihren eigenen Text und führen Sie ihn aus:

curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
  }' \
  --output response.json

Zeile für Zeile erklärt:

  • -X POST – Generierung ist ein zustandsändernder Aufruf, daher POST.
  • Die URL – die Basis-URL aus der Umgebungsvariable, gefolgt vom Modellbezeichner und /text-to-image. Anführungszeichen verhindern, dass die Shell Sonderzeichen falsch interpretiert.
  • Authorization: Bearer ... – die Anmeldedaten. Die Form $HIAPI_API_KEY verhindert, dass der eigentliche Schlüssel in der Shell-Historie erscheint.
  • Content-Type: application/json – teilt dem Server mit, den Anfragekörper als JSON zu parsen. Ihr Weglassen ist eine häufige Ursache für verwirrende 4xx-Fehler.
  • -d '{...}' – die JSON-Nutzlast. Das Feld prompt ist das, was Sie am häufigsten ändern; fügen Sie hier Generierungseinstellungen hinzu, während Sie die Ausgabe verfeinern.
  • --output response.json – schreibt den Antwortkörper in eine Datei, damit binäre Bildnutzlasten das Terminal nicht überfluten. Öffnen Sie sie, oder leiten Sie sie durch jq, wenn die Antwort JSON-kodiert ist.

Schnelle Plausibilitätsprüfung

Wenn der Befehl schnell zurückkehrt und response.json nicht leer ist, haben Sie eine funktionierende Integration. Wenn Sie stattdessen ein 4xx erhalten, prüfen Sie den Antwortkörper – HiAPI gibt beschreibende Fehler zurück, und der Abschnitt zur Fehlerbehandlung weiter unten behandelt die üblichen Verdächtigen.

Sobald dies funktioniert, speichern Sie den Befehl in einem Shell-Skript neben Ihrem Projekt. Das ist der schnellste Weg, um Änderungen an den Anmeldedaten zu testen oder zu bestätigen, ob ein Problem auf Ihrer Seite liegt.

Dieselbe Anfrage mit Python senden

Der curl-Aufruf lässt sich direkt in Python übersetzen. Dieses Skript verwendet nur die Standardbibliothek, liest den Schlüssel aus Umgebungsvariablen und schreibt die Bildantwort auf die Festplatte:

import json
import os
import urllib.error
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"

def generate_image(prompt: str, settings: dict | None = None) -> bytes:
    payload = {"prompt": prompt}
    if settings:
        payload.update(settings)

    request = urllib.request.Request(
        f"{BASE_URL}/{MODEL}",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            return response.read()
    except urllib.error.HTTPError as exc:
        detail = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc

if __name__ == "__main__":
    body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
    with open("output.bin", "wb") as f:
        f.write(body)
    print(f"wrote {len(body)} bytes")

Einige bewusste Entscheidungen:

  • Das Timeout ist großzügig bemessen. Die Bildgenerierung ist langsamer als die Textvervollständigung; ein Limit von 120 Sekunden verhindert endloses Hängen und toleriert dennoch langsame, aber erfolgreiche Aufrufe.
  • Die Funktion gibt Bytes zurück, keinen Pfad. Das macht sie wiederverwendbar – Sie können die Bytes in einen Objektspeicher hochladen oder aus einem Web-Handler zurückgeben.
  • Fehler werden verpackt und mit dem Antwortkörper versehen. Im Fehlerfall sagt Ihnen die Meldung, was der Server gesagt hat, nicht nur den Statuscode.
  • Der Nutzlast-Builder akzeptiert optionale Einstellungen. Wenn Sie Generierungsparameter hinzufügen, erweitern Sie das settings-Dictionary, statt sie in die Funktion fest einzubauen.

Exportieren Sie beide Umgebungsvariablen und führen Sie es mit python generate.py aus. Wenn Sie requests bevorzugen, ersetzen Sie den Anfrage-Aufbau durch requests.post(url, json=payload, headers=headers); die Struktur ist identisch.

Batch- und Concurrency-Muster

Ein Prompt ist eine Demo; viele Prompts sind Arbeit. Dieser Übergang bringt zwei Probleme mit sich: Durchsatz und Debugbarkeit.

Prompts aus einer Datei iterieren

Legen Sie die Prompts in einer zeilengetrennten Datei oder einem JSON-Array ab. Weisen Sie jedem Prompt eine ID zu (Slug, Index oder Hash) und benennen Sie die Ausgabedatei nach dieser ID. Wenn ein Batch von Hunderten Bildern fertig ist, können Sie jede Datei ohne Raten ihrem Prompt zuordnen.

prompts = [
    ("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
    ("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
    body = generate_image(text)
    with open(f"out/{prompt_id}.bin", "wb") as f:
        f.write(body)

Concurrency explizit steuern

Generierungsaufrufe sind I/O-intensiv, daher hilft Concurrency dem Durchsatz – aber unbegrenzte Concurrency löst Rate-Limits aus und lässt Sie im Fehlersumpf versinken. Beginnen Sie seriell, messen Sie die Dauer eines einzelnen Aufrufs und erhöhen Sie dann die Concurrency mit einem begrenzten Worker-Pool. Ein einfacher Thread-Pool mit einer kleinen festen Anzahl von Worker-Threads (vier bis acht zu Beginn) ist in der Regel ausreichend.

Für größere Aufgaben verwenden Sie einen asynchronen Client oder eine Queue mit Worker-Threads. Die entscheidende Disziplin bleibt dieselbe: begrenzte Parallelität, eine Ausgabedatei pro Prompt-ID, eine Logzeile pro Anfrage mit ID, Status und Dauer.

Ein Manifest führen

Schreiben Sie während des Batch-Laufs ein kleines JSON-Manifest, das jede Prompt-ID und ihr Ergebnis aufzeichnet. Wenn der Prozess mittendrin stirbt, sagt Ihnen das Manifest, wo Sie wiederaufnehmen können, statt den gesamten Batch erneut abzurechnen. Diese Praxis spart mehr Zeit als jede noch so clevere Optimierung.

Fehler und Wiederholungen behandeln

Fehler fallen in zwei Kategorien: solche, die Sie beheben, und solche, die Sie wiederholen. Sie zu verwechseln kostet Zeit und – bei einer Wiederholungsflut – auch Geld.

Diese beheben

  • 401 / 403 – Authentifizierung. Der Schlüssel fehlt, ist abgelaufen oder hat keine Zugriffsberechtigung. Prüfen Sie, ob HIAPI_API_KEY tatsächlich in der Shell exportiert ist, die den Befehl ausführt – ein häufiger Fallstrick ist, in einem Terminal zu exportieren und das Skript in einem anderen auszuführen.
  • 400 – fehlerhafte Nutzlast. Ungültiges JSON, fehlender prompt oder unerwartete Feldtypen. Der Fehlerkörper benennt normalerweise das problematische Feld. Achten Sie beim curl-Aufruf auf korrekte Anführungszeichen in Ihrem JSON.
  • 404 – falscher Pfad. Stellen Sie sicher, dass der Modellbezeichner genau wie in der Dokumentation geschrieben ist und Ihre Basis-URL keine doppelten oder fehlenden Pfadsegmente aufweist.

Diese mit Backoff wiederholen

  • 429 – Rate-Limit erreicht. Drosseln Sie die Geschwindigkeit. Beachten Sie alle retry-after-Hinweise in der Antwort und verwenden Sie exponentielles Backoff mit Jitter. Begrenzen Sie langfristig Ihre Concurrency.
  • 5xx – Serverfehler. In der Regel vorübergehend. Wiederholen Sie eine begrenzte Anzahl von Malen (drei ist eine sinnvolle Voreinstellung) mit steigender Verzögerung und lassen Sie dann deutlich scheitern.

Ein minimaler Wiederholungs-Wrapper

import random, time

def with_retries(fn, attempts=3):
    for i in range(attempts):
        try:
            return fn()
        except RuntimeError as exc:
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.uniform(0, 0.5))

Umschließen Sie damit generate_image. Entscheidend ist, die Operation von Ihrer Seite aus idempotent zu machen: Da die Ausgabedateien nach Prompt-ID benannt sind, überschreibt eine Wiederholung, statt zu duplizieren. Protokollieren Sie jeden Fehler mit Prompt-ID und Servermeldung – genau dieses Log benötigt das Support-Team, um das Problem zu reproduzieren, wenn Sie tatsächlich eskalieren müssen.

Nächste Schritte

Sie haben jetzt eine funktionierende Anfrage, eine Python-Funktion, die es sich zu behalten lohnt, und die Muster, um sie im großen Maßstab auszuführen. Um sie für die Produktion zu härten, fügen Sie strukturiertes Logging mit Request-IDs hinzu, persistieren Sie das Manifest in dauerhaftem Speicher, damit Batch-Jobs nach einem Absturz wiederaufnehmen können, und validieren Sie Prompts vor dem Senden, damit fehlerhafte Eingaben schnell und kostengünstig scheitern.

Der nützlichste nächste Schritt ist, genau diesen Client mit anderen Modellen auf der HiAPI API wiederzuverwenden. Da Endpunktpfad, Authentifizierungs-Header und Nutzlaststruktur gemeinsam genutzt werden, bedeutet die Anpassung des Skripts an ein neues Modell in der Regel nur, den Modellbezeichner und gelegentlich ein oder zwei Einstellungen zu ändern – eine kleine Codeänderung mit deutlich anderen Ausgaben.

Beginnen Sie mit einem Prompt, bestätigen Sie die Dateierzeugung und lassen Sie dann den Batch-Runner den Rest erledigen.

Ä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