So verwenden Sie imagen-4.0 über die HiAPI-API: curl, Python und funktionierende Anfragebeispiele

Was HiAPI Ihnen mit imagen-4.0 bietet

imagen-4.0 ist ein Text-zu-Bild-Modell: Sie senden eine natürlichsprachliche Eingabeaufforderung, und es gibt ein generiertes Bild zurück. Als integrierender Entwickler ist nicht die Architektur des Modells entscheidend, sondern die Schnittstellenvereinbarung darum herum. Über HiAPI ist diese Vereinbarung ein HTTP-Endpunkt – er akzeptiert JSON und authentifiziert mit einem Bearer-Schlüssel – was genau dem Muster entspricht, das Sie bereits von Chat-Completion- und Embedding-Aufrufen kennen.

Der praktische Vorteil von HiAPI gegenüber der direkten Anbindung an das Modell:

• Einheitliches Authentifizierungsschema. Derselbe API-Schlüssel gilt für alle Modelle der Plattform, sodass Sie nicht zwischen den Zugangsdaten mehrerer Anbieter wechseln müssen.
• Einheitliches Anfrageformat. Ein JSON-Anfragetext mit Modellkennung und Eingabeaufforderung. Sie müssen keine SDK-spezifische Anforderungsstruktur erlernen.
• Synchrones Ergebnis. imagen-4.0 gibt das Ergebnis in derselben HTTP-Antwort zurück, sodass Sie für Basisszenarien keine Polling-Schleife oder Webhooks einrichten müssen.

Diese Anleitung führt Sie von Grund auf durch den Aufbau je einer funktionierenden Anfrage mit curl und Python, erklärt dann, wie Sie die Antwort lesen und was Sie vor dem Produktivgang vorbereiten müssen.

API-Schlüssel beziehen und Authentifizierung einrichten

Jeder imagen-4.0-Aufruf bei HiAPI wird mit einem Bearer-Token authentifiziert. Sie erstellen einen API-Schlüssel in Ihrem HiAPI-Konto, und dieser Schlüssel ist danach die einzige Zugangsdaten, die die Anfrage benötigt – keine separate Projekt-ID, keine signierten Header.

Die Regel, die die meisten Unfälle vermeidet: Der Schlüssel gehört in eine Umgebungsvariable, niemals in den Quellcode. Ein Schlüssel, der in ein Skript eingefügt und in ein Repository gepusht wird, ist ein Schlüssel, den Sie rotieren müssen.

Lokale Einrichtung

Exportieren Sie den Schlüssel in Ihrer Shell-Sitzung:

export HIAPI_API_KEY="your-key-here"

Wenn Sie möchten, dass die Variable dauerhaft gilt, fügen Sie diese Zeile Ihrer Shell-Konfigurationsdatei hinzu; oder verwenden Sie eine .env-Datei, nehmen Sie sie in .gitignore auf und laden Sie sie beim Anwendungsstart.

Bereitgestellte Umgebungen

In CI und Produktion setzen Sie HIAPI_API_KEY über den Secret-Manager Ihrer Plattform – die Umgebungsvariable zur Laufzeit injizieren, statt eine Datei in das Image einzubacken. So ist Ihr Anwendungscode lokal und in bereitgestellten Umgebungen identisch, nur die Quelle der Variable unterscheidet sich.

Header

Jede Anfrage trägt:

Authorization: Bearer $HIAPI_API_KEY

Wenn Sie einen 401 sehen, prüfen Sie zuerst, ob der Header tatsächlich gesendet wird und ob die Variable zu einem nicht leeren Wert aufgelöst wird. Eine Shell, die die Variable nie exportiert hat, sendet getrost Bearer , gefolgt von nichts.

Die Anforderungsstruktur verstehen, bevor Sie senden

Der imagen-4.0-Anfragetext ist klein genug, um ihn im Kopf zu behalten, und das ist der Punkt – sobald Sie seine Struktur verstanden haben, können Sie die Anfrage in jeder Sprache konstruieren, ohne ein kopiertes Code-Snippet zu übersetzen.

Mindestens müssen Sie senden:

{
  "model": "imagen-4.0",
  "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
}

Zwei Felder leisten die Hauptarbeit:

• model gibt an, welches Modell die Anfrage verarbeitet. Es ist eine Zeichenkette und derselbe Bezeichner, den die Plattform überall verwendet, wo imagen-4.0 aufgeführt ist. Ein Tippfehler führt zu einer Fehlerantwort, nicht zu einem stillen Fallback.
• prompt ist die Beschreibung des Bildes, das Sie möchten. Schreiben Sie sie so, wie Sie einer Person eine Szene beschreiben würden: Motiv, Umgebung, Stil, Licht. Konkrete Eingabeaufforderungen erzeugen vorhersehbarere Ergebnisse als Ein-Wort-Eingabeaufforderungen.

Die Anfrage wird als POST mit Content-Type: application/json an den Bildgenerierungs-Endpunkt der Plattform gesendet. Das Modell mag zusätzliche optionale Parameter haben, aber der obige Anfragetext mit zwei Feldern ist eine vollständige, gültige Anfrage – beginnen Sie damit und fügen Sie Optionen nur bei Bedarf hinzu.

Da der Anfragetext reines JSON ist, sind curl, Python, Node und jedes Tool mit HTTP-Client gleichberechtigt. Die nächsten beiden Abschnitte zeigen zwei Schreibweisen derselben Anfrage.

Funktionierende curl-Anfrage

Beginnen Sie im Terminal, wo Sie die Rohantwort ohne jegliche Parsing-Störung sehen können.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0",
    "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
  }'

Zeile für Zeile erklärt:

• -sS unterdrückt den Fortschrittsbalken, zeigt aber Fehler an, sodass die Ausgabe lesbar bleibt und Fehler nicht verborgen werden.
• -X POST legt die Anforderungsmethode fest. Die Bildgenerierung erzeugt Inhalte, daher POST.
• Die URL ist der Bildgenerierungs-Endpunkt der Plattform, gebildet aus Ihrer Basis-URL plus Pfad. Bewahren Sie die Basis-URL in einer Variable auf, damit derselbe Befehl in verschiedenen Umgebungen verwendet werden kann.
• Der erste Header trägt Ihren Bearer-Schlüssel, gelesen aus der zuvor exportierten Umgebungsvariable.
• Content-Type: application/json teilt dem Server mit, wie der Anfragetext zu parsen ist.
• -d liefert den JSON-Anfragetext. Einfache Anführungszeichen verhindern, dass die Shell geschweifte Klammern und Anführungszeichen interpretiert; das JSON darin ist wörtlich.

Wenn Sie die Ausgabe prüfen möchten, verarbeiten Sie sie mit einem JSON-Formatierungswerkzeug:

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4.0","prompt":"A weathered lighthouse on a cliff at dusk"}' \
  | python -m json.tool

Wenn die Antwort eine Bildreferenz enthält, war die Anfrage erfolgreich. Der nächste Abschnitt wandelt sie in Anwendungscode um.

Dieselbe Anfrage in Python schreiben

Der curl-Aufruf lässt sich direkt übertragen. Die einzige wirkliche Wahl ist der HTTP-Client; das Standardbibliotheksmodul urllib funktioniert überall, aber requests ist kürzer und die Bibliothek, auf die die meisten Codebasen bereits angewiesen sind.

Wiederverwendbare Hilfsfunktion

import os
import requests

HIAPI_BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")


def generate_image(prompt: str, model: str = "imagen-4.0") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"model": model, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


result = generate_image("A weathered lighthouse on a cliff at dusk")
print(result)

Drei Dinge sind bemerkenswert:

• os.environ["HIAPI_API_KEY"] wirft bei fehlender Variable sofort einen KeyError und scheitert damit schnell und laut, statt ein leeres Token zu senden.
• json= serialisiert das Dictionary automatisch und setzt den Inhaltstyp, sodass sich die Anfrage genau wie die curl-Version verhält.
• timeout=120 begrenzt die Aufrufdauer. Die Bildgenerierung dauert länger als Textvervollständigung, daher ein großzügiger Timeout statt des Standardwerts ohne Timeout.

Die Funktion nimmt die Eingabeaufforderung als Parameter und gibt das geparste JSON zurück, sodass der Rest Ihres Codes keine HTTP-Details berühren muss. Testen Sie sie in der REPL, bevor Sie sie an irgendetwas anbinden.

Die synchrone Antwort lesen und Fehler behandeln

Die imagen-4.0-Antwort ist synchron: Das generierte Bild wird im Body derselben HTTP-Antwort zurückgegeben. In Basisszenarien gibt es keine Job-ID zum Abfragen und keine Polling-Schleife zu schreiben – behandeln Sie diesen Aufruf wie jede andere Request-Response-Interaktion.

Was zurückgegeben wird

Eine erfolgreiche Antwort ist ein JSON-Objekt. Parsen Sie sie in Python mit response.json() oder leiten Sie die curl-Ausgabe durch ein JSON-Formatierungswerkzeug, und lokalisieren Sie dann die Bilddaten in der Rückgabestruktur – üblicherweise eine URL oder ein kodierter Bildnutzlastwert sowie Metadaten zur Generierung. Lesen Sie die genauen Feldnamen einmal aus einer echten Antwort ab und schreiben Sie dann Ihren Code darauf basierend.

Worauf Sie achten müssen

Umschließen Sie den Aufruf und prüfen Sie den Status, bevor Sie parsen:

try:
    result = generate_image("A weathered lighthouse on a cliff at dusk")
except requests.HTTPError as e:
    print("HTTP error:", e.response.status_code, e.response.text)
except requests.Timeout:
    print("Request timed out")

Fehlermuster, die eine explizite Behandlung verdienen:

• 401 — Schlüssel fehlt oder ist ungültig. Beheben Sie die Umgebungsvariable, nicht den Code.
• Allgemeine 4xx — fehlerhaft formatierter Anfragetext, falsche Modellkennung oder abgelehnte Eingabeaufforderung. Der Antwortbody gibt normalerweise an, welcher Fall vorliegt. Protokollieren Sie ihn.
• 5xx — serverseitiger Fehler. Diese verdienen einen erneuten Versuch mit Backoff.
• Timeouts — behandeln Sie sie als unbekanntes Ergebnis, nicht als Erfolg; gehen Sie nicht davon aus, dass das Bild erzeugt wurde.

Protokollieren Sie bei Fehlern immer den Statuscode und den gekürzten Antwortbody. Ohne diese Informationen ist Debugging reine Vermutung.

Von der ersten Anfrage zum Produktivbetrieb

Die Anfrage funktioniert. Bevor Sie skalieren, prüfen Sie Punkt für Punkt:

• Konfiguration. Basis-URL und API-Schlüssel stammen beide aus der Umgebung. Keine Literale im Quellcode, keine Schlüssel im Image.
• Timeouts. Jeder Bildaufruf hat einen Timeout. Ohne Timeout kann eine hängende Anfrage einen Worker unbegrenzt belegen.
• Wiederholungen. Wiederholen Sie nur bei 5xx und Timeouts, mit exponentiellem Backoff und Obergrenze. Wiederholen Sie niemals 401 oder 4xx mit fehlerhaftem Anfragetext – sie scheitern auf genau dieselbe Weise.
• Protokollierung. Protokollieren Sie Modell, Länge der Eingabeaufforderung, Statuscode und Latenz jedes Aufrufs. Protokollieren Sie keine Schlüssel und keine vollständigen Eingabeaufforderungen, wenn diese Benutzerdaten enthalten könnten.
• Kostenbewusstsein. Die Bildgenerierung wird nach erzeugter Ausgabe abgerechnet, daher verfolgen Sie, wie viele Bilder pro Benutzer oder pro Job angefordert werden, und setzen Sie Obergrenzen auf Anwendungsebene. Aktuelle Tarife finden Sie im Preisbereich der Plattform, nicht in dieser Anleitung.
• Nebenläufigkeit. Bildaufrufe sind langsamer als Textaufrufe. Dimensionieren Sie den Worker-Pool entsprechend und gehen Sie nicht von der Latenz von Chat-Completion aus.

Sobald dies erledigt ist, kann dieselbe Hilfsfunktion generate_image ohne Änderung für Batch-Jobs, benutzergerichtete Funktionen und interne Tools verwendet werden. Weitere Integrationsdetails finden Sie in der Plattformdokumentation.