Blog

Tutorial

So rufen Sie fibo-2.0/text-to-image über die HiAPI API auf: curl und Python in der Praxis

Nov 13, 2026
Titelbild: Halbtransparente Glasebenen schichten sich auf einem hellgraublauen Hintergrund und brechen ein zurückhaltendes blaues Farbband, das eine abstrakte geometrische Komposition bildet.
Auf dieser Seite

Was dieses Tutorial aufbaut

Dies ist ein praxisorientierter Leitfaden, der Sie Schritt für Schritt dazu bringt, über fibo-2.0/text-to-image auf HiAPI tatsächlich ein Bild zurückzubekommen. Am Ende halten Sie zwei Dinge in der Hand, die Sie sofort ausführen können: einen curl-Befehl, der eine gültige Bildgenerierungsanfrage erzeugt, und eine kleine Python-Funktion, die dasselbe tut und das Ergebnis zur Weiterverarbeitung zurückgibt.

Wir gehen in der Reihenfolge vor, in der die meisten Entwickler tatsächlich arbeiten. Zuerst stellen wir sicher, dass Umgebung und Zugangsdaten bereitstehen. Dann lesen wir den Request-Body Feld für Feld durch, damit Sie klar sehen, was jeder Teil steuert. Anschließend senden wir den Aufruf mit curl, um zu belegen, dass Endpunkt, Schlüssel und Payload zusammenpassen. Erst danach portieren wir dieselbe Anfrage nach Python, wo die eigentlich interessante Arbeit beginnt – Antworten parsen, Fehler behandeln und alles in eine Funktion kapseln.

Das Ziel ist nicht, alle möglichen Parameter aufzuzählen, sondern Ihnen eine Request-Form zu geben, die Sie vollständig verstehen, sodass Sie Prompt, Ausgabegröße und umgebenden Code an Ihren eigenen Anwendungsfall anpassen können, ohne raten zu müssen.

Bevor Sie die erste Anfrage senden

Drei Voraussetzungen müssen erfüllt sein, bevor der erste Aufruf gelingt.

HiAPI-Konto und API-Schlüssel

Anfragen an fibo-2.0/text-to-image erfordern Authentifizierung. Erzeugen Sie einen API-Schlüssel in Ihrem HiAPI-Konto und halten Sie ihn von der Versionsverwaltung fern. Die folgenden Beispiele lesen den Schlüssel aus einer Umgebungsvariable statt ihn fest zu kodieren – tun Sie das vom ersten Tag an, denn das nachträgliche Einbauen einer Schlüsselverwaltung ist mühsam.

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

Ein Werkzeug, das HTTP-Anfragen senden kann

Für den praktischen curl-Teil benötigen Sie curl auf Ihrem Rechner. Es ist bei macOS und den meisten Linux-Distributionen dabei; unter Windows ist es in aktuellen Versionen und im Windows Terminal verfügbar. Für den Python-Teil benötigen Sie Python 3 und die requests-Bibliothek, die gebräuchlichste Art, HTTP-Aufrufe aus einem Skript heraus zu starten. Falls Sie sie noch nicht installiert haben:

pip install requests

Klarheit darüber, was Sie generieren möchten

Halten Sie einen Prompt bereit. Bildmodelle reagieren stark auf konkrete, eindeutige Beschreibungen – Motiv, Stil, Beleuchtung und Komposition –, daher reicht eine einzige Idee meist aus, um mit dem Testen zu beginnen. Sie werden sie nach dem ersten Ergebnis weiter verfeinern; das ist ein normaler Zyklus.

Sobald diese drei Punkte stehen, dreht sich alles Weitere um den Request-Body.

Die Anfrage Feld für Feld erklärt

Ein Aufruf von fibo-2.0/text-to-image ist eine POST-Anfrage mit einem JSON-Body. Der Body ist klein: ein Prompt und Einstellungen, die die Ausgabe formen. Statt sich die vollständige Payload einzuprägen, verstehen Sie besser jedes Feld, damit Sie es bewusst ändern können.

Modellkennung

Der Endpunktpfad selbst benennt das Modell: fibo-2.0/text-to-image. In den meisten Fällen müssen Sie keinen zusätzlichen Modellstring übergeben – die Route, die Sie aufrufen, bestimmt, welches Modell läuft. Wenn Ihre Integration Routing über einen gemeinsamen Endpunkt unterstützt, legen Sie den Modellnamen in einer Konfigurationskonstante ab, sodass Sie ihn wechseln können, ohne die Aufrufstelle zu ändern.

Der Prompt

Das ist die zentrale Eingabe: die Textbeschreibung des Bildes, das Sie möchten. Behandeln Sie ihn wie eine Spezifikation, nicht wie einen Wunsch. Motiv, visueller Stil und Komposition zu benennen gibt dem Modell mehr verwertbare Informationen als abstrakte Konzepte. Legen Sie den Prompt in einer Variable oder einer separaten Datei ab, damit Sie schnell iterieren können, ohne den Anfragecode neu zu schreiben.

Ausgabeeinstellungen

Bildanfragen tragen üblicherweise eine kleine Reihe von Ausgabesteuerungen – am häufigsten die Größe oder das Seitenverhältnis des generierten Bildes und, falls Sie mehrere Ergebnisse wünschen, deren Anzahl. Verwenden Sie die in der HiAPI-Modellreferenz für fibo-2.0/text-to-image dokumentierten Feldnamen; die folgende Beispiel-Payload verwendet diese kanonischen Namen. Wenn eine Einstellung für dieses Modell nicht dokumentiert ist, lassen Sie sie weg, statt zu raten – unbekannte Felder sind eine häufige Quelle von Validierungsfehlern.

Was nicht in den Request-Body gehört

Legen Sie den API-Schlüssel nicht in den JSON-Body. Authentifizierung gehört in die Request-Header. Wenn Zugangsdaten aus der Payload herausbleiben, kann der Body beim Debuggen sicher protokolliert und verglichen werden – was Sie zu schätzen wissen werden, wenn die erste Anfrage fehlschlägt.

Eine funktionierende curl-Anfrage

Hier ist ein vollständiger Aufruf. Ersetzen Sie Ihren eigenen Prompt und führen Sie ihn in einer Shell aus, in der HIAPI_API_KEY gesetzt ist.

curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Ein ruhiger Hafen im Morgengrauen, leichter Dunst über dem Wasser, breite Komposition, fotografischer Stil",
    "size": "1024x1024",
    "n": 1
  }'

Was jeder Teil bewirkt

  • -X POST setzt die HTTP-Methode. Bildgenerierung ist eine erzeugende Operation, also POST, nicht GET.
  • Die URL zeigt auf die Route fibo-2.0/text-to-image auf dem HiAPI-API-Host. Wenn Ihr Konto eine regionale oder projektspezifische Basis-URL verwendet, ersetzen Sie den Host und behalten Sie den Pfad bei.
  • Authorization: Bearer $HIAPI_API_KEY übergibt Ihren Schlüssel aus der Umgebung. Die Shell expandiert die Variable, sodass der Schlüssel nie als wörtlicher String in Ihrer Befehlsgeschichte auftaucht.
  • Content-Type: application/json teilt dem Server mit, dass der Body JSON ist. Ohne ihn weisen viele Gateways die Anfrage ab, bevor sie das Modell erreicht.
  • -d '...' ist der JSON-Body: der Prompt, die angeforderte Größe und die Anzahl von einem Bild.

Das Ergebnis überprüfen

Führen Sie den Befehl aus und sehen Sie sich zuerst die Rohausgabe an. Ein erfolgreicher Aufruf gibt ein JSON-Dokument zurück, das das generierte Bild beschreibt; ein fehlgeschlagener Aufruf gibt ein Fehlerobjekt zurück. Bevor Sie irgendetwas darauf aufbauen, stellen Sie sicher, dass Sie beide mit bloßem Auge unterscheiden können. Wenn die Antwort groß ist, verarbeiten Sie sie mit einem Formatierungswerkzeug wie jq, damit die Struktur lesbar wird:

curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Ein ruhiger Hafen im Morgengrauen","size":"1024x1024","n":1}' | jq .

Sobald der manuelle Aufruf gelingt, haben Sie Zugangsdaten und Payload als Verdächtige ausgeschlossen. Alle weiteren Probleme liegen danach in Ihrem Code.

Derselbe Aufruf in Python

Die Python-Version tut genau das, was der Shell-Befehl tut, gibt Ihnen aber einen Ort zum Validieren von Eingaben, Wiederholen von Versuchen und Speichern von Ergebnissen. Halten Sie sie klein und explizit.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"

def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    payload = {
        "prompt": prompt,
        "size": size,
        "n": n,
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate_image(
        "Ein ruhiger Hafen im Morgengrauen, leichter Dunst über dem Wasser, breite Komposition, fotografischer Stil"
    )
    print(result)

Warum es so geschrieben ist

  • Der Schlüssel wird innerhalb der Funktion aus der Umgebung gelesen, sodass der Aufruf beim Start laut fehlschlägt, wenn er fehlt, statt eine nicht authentifizierte Anfrage zu senden.
  • json=payload lässt requests den Body serialisieren und den Inhaltstyp korrekt setzen. Bauen Sie JSON-Strings in Python nicht von Hand zusammen; das führt zu Anführungszeichenfehlern, die erst zur Laufzeit auffallen.
  • timeout=60 macht langsame Fehler explizit. Bildgenerierung ist nicht sofort, also wählen Sie ein Timeout, auf das Sie zu warten bereit sind – aber setzen Sie unbedingt eines.
  • raise_for_status() verwandelt 4xx- und 5xx-Antworten in Ausnahmen. Genau diese Zeile verhindert, dass fehlgeschlagene Aufrufe stillschweigend als Erfolg behandelt werden.
  • Die Funktion nimmt prompt, size und n als Parameter, sodass der Rest Ihres Programms sie wie jede andere Bibliotheksfunktion aufrufen kann.

Führen Sie die Datei aus; Sie sollten dieselbe JSON-Struktur sehen, die der curl-Aufruf zurückgibt.

Antworten lesen und Fehler behandeln

Eine erfolgreiche Antwort liefert Ihnen ein JSON-Objekt, das die generierte Ausgabe beschreibt. Das Detail, das Sie interessiert, ist das generierte Bild selbst – üblicherweise eine URL oder Referenz, die Sie herunterladen oder speichern können – sowie alle Metadaten, die die API zur Anfrage zurückgibt. Parsen Sie die Antwort als Daten; greifen Sie sie nicht mit String-Operationen ab. Wenn die Form beim ersten Prüfen der Live-Antwort nicht wie erwartet aussieht, konsultieren Sie zuerst die Modellreferenz, bevor Sie den Parser anpassen, denn das Raten von Feldnamen ist genau die Art, wie Integrationen heimlich brechen.

Fehler erkennen

Drei Fehlerbenen sollten Sie bewusst behandeln.

Transportfehler. Die Anfrage wurde nie abgeschlossen: DNS-Fehler, Verbindungsabbruch, Timeout. In Python erscheinen diese als requests.exceptions; sie sind sicher und können mit Backoff wiederholt werden.

HTTP-Fehlerstatus. Der Server hat geantwortet, aber die Anfrage abgelehnt. 401 bedeutet meist, dass der Schlüssel fehlt oder falsch ist; 4xx-Validierungsfehler bedeuten meist, dass ein Feldname oder Wert nicht stimmt; 429 bedeutet, dass Sie zu schnell senden; 5xx bedeutet, dass serverseitig etwas schiefgelaufen ist. raise_for_status() fängt all diese als eine Ausnahme ein, prüfen Sie daher die Nachricht im Antwort-Body, bevor Sie entscheiden, was zu tun ist.

Statuscode 200, aber unerwarteter Antwort-Body. Deshalb validieren Sie die Struktur, statt sie anzunehmen. Prüfen Sie vor der Verwendung, ob die Felder vorhanden sind, auf die Sie sich verlassen, und behandeln Sie eine fehlende Bildreferenz auch bei Statuscode 200 als Fehler.

try:
    result = generate_image("Ein ruhiger Hafen im Morgengrauen")
    image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
    print("request failed:", exc.response.status_code, exc.response.text)

Wichtige Gewohnheit: Fehler niemals stillschweigend verschlucken. Protokollieren Sie mindestens Statuscode und Antwort-Body, denn genau dieses Paar sagt Ihnen, ob Sie die Payload reparieren oder warten und erneut versuchen sollten.

Richtung Produktivumgebung

Sobald ein einzelner Aufruf funktioniert und Fehler sichtbar sind, sorgen einige kleine Gewohnheiten dafür, dass die Integration unter realem Traffic standhält.

Nur sichere Wiederholungen erneut versuchen

Transportfehler, Timeouts, 429- und 5xx-Antworten verdienen Wiederholungen mit exponentiellem Backoff und einer Obergrenze für Versuche. Validierungsfehler und 401 nicht – eine fehlerhafte Anfrage erneut zu senden verbraucht nur Kontingent. Unterscheiden Sie diese beiden Kategorien ausdrücklich in Ihrer Fehlerbehandlung.

Konfiguration aus dem Code heraushalten

Legen Sie API-Basis-URL, Modellpfad, Standardgröße und Timeout in der Konfiguration ab, statt sie über Funktionen zu verstreuen. Wenn Sie von Test- zu anderen Umgebungen wechseln oder später ein ähnliches Modell ausprobieren, ändern Sie nur eine Stelle.

Anfragen und Antworten protokollieren, aber ohne Schlüssel

Protokollieren Sie Prompts, Parameter, Statuscodes und gekürzte Antworten. Protokollieren Sie niemals den API-Schlüssel. So können Sie eine Woche später die Frage „Warum kam dieses Bild falsch zurück?“ beantworten, ohne es reproduzieren zu müssen.

Eingaben vor dem Senden validieren

Prüfen Sie, dass der Prompt nicht leer und von angemessener Länge ist, und prüfen Sie, dass size und n zu den dokumentierten Werten des Modells passen. Fehlerhafte Werte lokal abzufangen ist schneller und günstiger als ein Roundtrip.

Ergebnisse speichern, nicht nur ausgeben

Generierte Bildreferenzen können temporär sein. Laden Sie die Ausgabe als Teil desselben Jobs herunter oder kopieren Sie sie in Ihren eigenen Speicher, und halten Sie fest, welcher Prompt und welche Parameter sie erzeugt haben. Dieser Datensatz ermöglicht Regenerierung und Audits.

Kapseln Sie fibo-2.0/text-to-image hinter der kleinen generate_image-Funktion aus diesem Tutorial und lassen Sie den Rest Ihrer Anwendung sich auf diese Funktion verlassen statt auf rohe HTTP-Aufrufe. Wenn Sie bereit sind, Prompts im großen Maßstab zu variieren, ist die HiAPI-Modellreferenz der Ort, an dem Sie vor dem Erweitern der Schnittstelle die unterstützten Parameter bestätigen.

Ä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