Tutorial
So rufen Sie fibo-2.0/image-to-image über die HiAPI API auf: Praxis mit curl und Python
Auf dieser Seite
Die Rolle von fibo-2.0/image-to-image in der Pipeline
Text-zu-Bild-Modelle beginnen mit einem Prompt, Bild-zu-Bild-Modelle beginnen mit einem Bild, das Sie bereits haben. Dieser Unterschied wirkt klein, bestimmt aber die Position des Modells in der Pipeline: fibo-2.0/image-to-image ist nicht der erste Schritt, der Material erzeugt, sondern ein Bearbeitungsschritt, der vorhandene Bilder umgestaltet.
Ein typischer Workflow sieht so aus: Sie beschaffen oder erzeugen ein Basisbild, schicken es mit einer Anweisung, die die gewünschte Änderung beschreibt, an fibo-2.0/image-to-image und geben das zurückgegebene Ergebnis an nachgelagerte Schritte weiter – Prüfung, Komposition, Speicherung oder einen weiteren Modellaufruf. Da das Modell sowohl das Eingabebild als auch den Prompt erhält, kann es Stil, Beleuchtung oder die von Ihnen beschriebenen Teile neu zeichnen und dabei Komposition, Position des Motivs und Gesamtstruktur bewahren.
Wann Bild-zu-Bild statt Text-zu-Bild wählen
Wählen Sie Bild-zu-Bild, wenn die Ausgabe eine erkennbare Verbindung zum vorhandenen Bild behalten soll: ein Foto neu stylen, ohne das Motiv zu verändern, Beleuchtung oder Farbanmutung anpassen, Varianten bereits freigegebener Assets erzeugen oder ein grobes Basismaterial vor der finalen Verwendung bereinigen. Wenn Sie kein Ausgangsbild, sondern nur eine Beschreibung haben, wählen Sie Text-zu-Bild.
Was die Schnittstelle von Ihnen verlangt
Der Aufruf ist eine Job-Übermittlung: Sie senden das Eingabebild, den Prompt und die Parameter, die Sie steuern möchten, und die API gibt einen nachverfolgbaren Job zurück. Betrachten Sie diese Schnittstelle als klar definierte Stufe in einer größeren Kette und nicht als vollständige Bearbeitungsanwendung – wie Sie das Eingabebild vorbereiten und wie Sie das Ergebnis behandeln, liegt bei Ihnen.
Da die Anfrage im Kern asynchron ist, sollte auch das Integrationsdesign darauf ausgerichtet sein: übermitteln, die Job-ID speichern, pollen bis der Job abgeschlossen ist und dann die Ausgabereferenz abrufen. Der Rest dieses Leitfadens baut genau diesen Ablauf auf.
Vorbereitung vor dem Senden der Anfrage
Vor dem ersten Aufruf brauchen Sie drei Dinge: Zugangsdaten, ein korrektes Verständnis der Schnittstellenform und ein vorbereitetes Eingabebild.
Zugangsdaten
Alle Anfragen an die HiAPI API werden mit einem API-Schlüssel authentifiziert. Der Schlüssel muss serverseitig aufbewahrt werden – betten Sie ihn niemals in Browsercode ein und committen Sie ihn nicht ins Repository. Am saubersten lesen Sie ihn aus einer Umgebungsvariable, sodass derselbe Code lokal und in der Deployment-Umgebung funktioniert:
export HIAPI_API_KEY="your-api-key"
Falls Sie noch keinen Schlüssel haben, erstellen Sie zuerst einen in der HiAPI-Kontokonsole und fahren Sie dann fort.
Schnittstellenform
Das Modell hat in der HiAPI API die Kennung fibo-2.0/image-to-image. Alle Modellaufrufe teilen dieselbe Basis-URL und dieselben Request-Konventionen. Das bedeutet: Sobald ein Aufruf funktioniert, besteht der Wechsel zu einem anderen Modell im Wesentlichen darin, Modellkennung und Payload-Felder zu ändern.
Eingabebild vorbereiten
Eine Bild-zu-Bild-Anfrage benötigt ein echtes Bild und nicht eine URL, von der Sie hoffen, dass sie interpretiert wird. Überlegen Sie sich vorab, wie Sie es bereitstellen: als lokale Datei, die mit der Anfrage hochgeladen wird, oder als Referenz, die die API akzeptiert; und prüfen Sie vor dem Schreiben von Anwendungscode, ob das Format funktioniert. Die zwei häufigsten Fehlerquellen bei ersten Anfragen sind: einen Pfad zu senden, der nur auf Ihrem Notebook existiert, und eine Datei in einem Format zu senden, das die Schnittstelle nicht akzeptiert.
Eine praktische Checkliste vor dem Aufbau des Aufrufs:
- Das Bild ist eine echte Datei, die Ihre Sprache lesen kann.
- Der Prompt beschreibt die gewünschte Bearbeitung in klarer Sprache und ist nicht nur eine Anhäufung von Stichwörtern.
- Sie wissen, welche Parameter Sie übergeben und welche Sie auf den Standardwerten belassen.
- Ihr API-Schlüssel ist in der Umgebung auffindbar, die die Anfrage ausführt.
Sobald dies bereit ist, können Sie zur Anfrage selbst übergehen.
Eine funktionierende curl-Anfrage Zeile für Zeile erklärt
Beginnen Sie mit curl. Es beseitigt jede Abstraktion zwischen Ihnen und der HTTP-Anfrage; wenn etwas schiefgeht, wissen Sie, dass das Problem in der Anfrage und nicht in einer Client-Bibliothek liegt.
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fibo-2.0/image-to-image",
"prompt": "turn the scene into a soft watercolor illustration, keep the subject and framing",
"image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
"n": 1
}'
Im Folgenden wird erläutert, was die einzelnen Teile bewirken.
Die Anfragezeile
-X POST legt die Methode fest. Die URL ist die HiAPI-API-Basisadresse plus dem Pfad zur Bilderzeugung. Legen Sie die Basisadresse in einer Variable oder einem Konfigurationswert ab, statt sie an mehreren Stellen hart zu codieren, sodass künftige Änderungen nur an einer Stelle nötig sind.
Die Header
Authorization: Bearer $HIAPI_API_KEY überträgt Ihre Zugangsdaten; die Shell expandiert die zuvor exportierte Umgebungsvariable, sodass der Schlüssel nicht im Klartext in der Befehlshistorie erscheint. Content-Type: application/json teilt der API mit, den Request-Body als JSON zu parsen. Einen JSON-Body zu senden und diesen Header wegzulassen, ist eine häufige Ursache für schwer verständliche Fehler.
Die Payload
model identifiziert fibo-2.0/image-to-image. prompt ist Ihre Anweisung – beschreiben Sie die Bearbeitung, nicht das gesamte Ausgabebild, denn das Eingabebild trägt bereits die Struktur. image ist die von der Schnittstelle akzeptierte Form des Eingabebilds; bei direkter Einbettung ist dies der base64-codierte Dateiinhalt. n steuert die Anzahl der angeforderten Ausgaben; der Standardwert ist der sicherste Ausgangspunkt.
Bei großen Bildern wird das direkte Einbetten in einen Shell-Befehl unhandlich. Codieren Sie das Bild zuerst in eine Datei und referenzieren Sie diese, oder wechseln Sie direkt zur Python-Methode im nächsten Abschnitt – dort sind Lesen und Codieren der Datei eine Zeile.
Die Antwort lesen
Gehen Sie nicht davon aus, dass die Antwort fertige Bildbytes enthält. Führen Sie den curl-Aufruf aus und prüfen Sie das JSON: Sie suchen eine Job-ID oder ein Statusfeld, um zu erkennen, ob die Aufgabe abgeschlossen ist oder noch läuft. Erfassen Sie die Struktur, bevor Sie Parsing-Code schreiben, denn die Form der Antwort bestimmt, wie Sie pollen.
Die Anfrage nach Python portieren
Python macht die Anfrage wartbarer und ermöglicht es, sie in einer Funktion zu kapseln, die in der gesamten Codebasis wiederverwendet werden kann. Hier ist ein schlanker Client für dieselbe Anfrage:
import base64
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
def encode_image(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
def submit_image_edit(image_path: str, prompt: str) -> dict:
payload = {
"model": "fibo-2.0/image-to-image",
"prompt": prompt,
"image": encode_image(image_path),
"n": 1,
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
Warum diese Struktur
Durch die Trennung von encode_image und submit_image_edit bleiben Dateiverarbeitung und HTTP-Verarbeitung unabhängig und jeweils leichter testbar. Den Schlüssel beim Import aus der Umgebung zu lesen, lässt den Code sofort fehlschlagen, wenn er fehlt, statt erst mehrere Ebenen später einen 401 zu erzeugen. Ein explizites timeout verhindert, dass eine hängende Verbindung einen Worker unbegrenzt blockiert.
Den Response-Body behandeln
raise_for_status() verwandelt Fehler auf HTTP-Ebene in Ausnahmen, die abgefangen und mit geloggtem Response-Body versehen werden können – das ist weit nützlicher, als ein Fehlerobjekt stillschweigend als Erfolg zu parsen. Nachdem Sie das geparste JSON erhalten haben, protokollieren Sie die enthaltene Job-ID und während der Entwicklung die vollständige Antwort, um genau zu sehen, welche Felder vorhanden sind. Schreiben Sie keinen Parser auf Basis von Annahmen, sondern auf Basis der tatsächlich beobachteten Antwort.
Wiederverwendbarkeit erhalten
Zwei kleine Verbesserungen zahlen sich schnell aus: Basis-URL und Modellname in Konstanten ablegen, damit andere Modellaufrufe denselben Client nutzen; und die Submit-Funktion eine typisierte Struktur zurückgeben lassen (eine kleine Dataclass oder ein dict mit bekannten Schlüsseln), damit der Polling-Code einen stabilen Vertrag hat.
Den asynchronen Lebenszyklus und das Polling behandeln
Bildjobs werden nicht sofort fertiggestellt. Die Integration sollte Übermittlung und Abschluss als zwei getrennte Ereignisse behandeln.
Schritt 1: Übermitteln und persistieren
Nach dem Übermitteln des Jobs speichern Sie die Job-ID an einem persistenten Ort – eine Datenbankzeile, eine Queue-Nachricht oder zumindest eine Logzeile. Wenn der Prozess zwischen Übermittlung und Abschluss abstürzt, ist ein nicht erfasster Job verlorene Arbeit. Verknüpfen Sie die ID mit der Entität in Ihrem System, der das Ergebnis gehört, damit Sie später abgleichen können.
Schritt 2: Polling mit Backoff
Pollen Sie den Endpunkt für den Job-Status in einem sinnvollen Intervall. Eine enge Schleife, die den Status-Endpunkt wiederholt bombardiert, verschwendet Ressourcen und ist der häufigste asynchrone Fehler:
def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
response = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
job = response.json()
if job.get("status") in {"succeeded", "failed"}:
return job
time.sleep(interval)
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
Mit einem kurzen Intervall zu beginnen und es schrittweise zu erhöhen, hält frühe Prüfungen reaktionsschnell und vermeidet zugleich langfristig hochfrequente Anfragen. Eine harte Frist verhindert unbegrenztes Warten auf einen Job, der nie abgeschlossen wird.
Schritt 3: Fehler als normales Ergebnis behandeln
Ein abgeschlossener Job ist nicht zwangsläufig ein erfolgreicher Job. Prüfen Sie den Status, bevor Sie die Ausgabe lesen, und verzweigen Sie explizit für Fehler: Protokollieren Sie die vom Job zurückgegebenen Fehlerdetails, senden Sie ein Wiederholungssignal an den Aufrufer und entscheiden Sie, ob ein erneuter Versuch dieselbe Eingabe wiederverwendet oder neu erzeugt werden soll. Ein clientseitig bereits abgelaufener Job kann serverseitig noch laufen; übermitteln Sie ihn daher nicht blind erneut, ohne zu prüfen.
Schritt 4: Ergebnis abrufen und speichern
Sobald der Job Erfolg meldet, lesen Sie die bereitgestellte Ausgabereferenz und laden Sie das Ergebnis zeitnah herunter. Für eine langfristige Speicherung des Ergebnisses kopieren Sie es in Ihren eigenen Speicher, statt sich darauf zu verlassen, dass die Referenz dauerhaft gültig bleibt.
Häufige Fehler und wie man sie behebt
Die meisten Fehler lassen sich einigen vorhersehbaren Kategorien zuordnen. Gehen Sie diese Liste der Reihe nach durch.
Authentifizierungsfehler
401 oder 403 bedeutet fast immer einen falschen Header oder einen fehlenden Schlüssel. Stellen Sie sicher, dass der Header exakt Authorization: Bearer <key> lautet, mit einem Leerzeichen nach Bearer; und stellen Sie sicher, dass die Umgebungsvariable tatsächlich in dem Prozess gesetzt ist, der die Anfrage ausführt – nicht nur in Ihrer interaktiven Shell. Beim Einfügen des Schlüssels entstandene nachgestellte Leerzeichen oder überflüssige Anführungszeichen machen einen erheblichen Anteil dieser Probleme aus.
Falsch formatierte Payload
400 oder 422 bedeutet meist, dass die API den Request-Body nicht interpretieren kann. Prüfen Sie drei Dinge der Reihe nach: ob Content-Type: application/json vorhanden ist, ob das JSON tatsächlich parsebar ist (nachgestellte Kommas brechen es) und ob die erforderlichen Felder mit den korrekten Namen vorhanden sind. Wenn Sie base64-Bilddaten senden, prüfen Sie, ob es gültiges base64 ist und ob das zugrunde liegende Dateiformat unterstützt wird – abgeschnittene oder doppelt codierte Strings führen zu verwirrenden Validierungsfehlern.
Polling-Fehler
Wenn ein Job scheinbar nie abgeschlossen wird, prüfen Sie, ob Sie mit der Kennung pollen, die die Submit-Antwort tatsächlich zurückgegeben hat, und ob Sie das richtige Statusfeld lesen. Eine enge Schleife, die den Status failed ignoriert, sieht wie ein Hänger aus. Fügen Sie ein hartes Timeout hinzu und protokollieren Sie die beobachteten Statusänderungen; dieses Log deckt das Problem meist sofort auf.
Fallstricke beim Parsen von Antworten
Wenn Ihr Code beim Lesen des Ergebnisses eine Ausnahme wirft, raten Sie nicht an der Antwortform herum. Protokollieren Sie zuerst den rohen Response-Body. Häufige Probleme sind: eine Referenz irrtümlich als Bytes behandeln, Felder, die nur bei Erfolg existieren, als immer vorhanden annehmen und einen Parser für den Erfolgspfad auf eine Fehlerantwort anwenden. Bauen Sie die Extraktionslogik auf Basis der Antworten, die Sie tatsächlich gesehen haben.
Gewohnheit zur schnellen Triage
Wenn etwas schiefgeht, isolieren Sie zuerst die Ebene: Führen Sie den curl-Befehl mit derselben Payload aus. Wenn curl erfolgreich ist und Python scheitert, liegt der Fehler im Client; wenn beides scheitert, liegt der Fehler in der Anfrage. Dieser einfache Test spart mehr Zeit als jede andere Debugging-Gewohnheit.
Mit einem funktionierenden Aufruf und einer robusten Polling-Schleife wird fibo-2.0/image-to-image zu einem zuverlässigen Bearbeitungsschritt – beginnen Sie auf der Modellseite von HiAPI und passen Sie die obige Anfrage an Ihre eigenen Bilder an.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen