Tutorial
So rufst du fibo-edit-1.5 Image-to-Image über die HiAPI API auf: curl- und Python-Leitfaden
Praxisnahe Erläuterung lauffähiger Anfragen für instruktionsbasierte Bildbearbeitung
Auf dieser Seite
Was der Image-to-Image-Endpunkt von fibo-edit-1.5 leistet
fibo-edit-1.5/image-to-image ist ein instruktionsgesteuerter Bildbearbeitungs-Endpunkt. Er beschreibt keine Szene von Grund auf neu, sondern nimmt ein Referenzbild und eine Anweisung in natürlicher Sprache entgegen und liefert ein neues Bild zurück, auf das diese Bearbeitung angewendet wurde, während der Rest der Komposition unverändert bleibt.
Diese Ausrichtung wirkt sich unmittelbar darauf aus, wie du Anfragen gestaltest. Das Referenzbild trägt den visuellen Kontext – Motiv, Bildausschnitt, Beleuchtung, Stil –, die Anweisung trägt die Änderung. Eine gute Anweisung sagt ausdrücklich, was geändert werden soll, und schweigt zu dem, was unverändert bleiben soll. „Ersetze den Himmel durch einen bewölkten Sonnenuntergang und lasse Gebäude und Vordergrund unverändert“ vermittelt mehr als „Mach es schöner“.
Ein erfolgreicher Aufruf erzeugt eine bearbeitete Bildressource. Je nach Aufrufart des Endpunkts wird die generierte Ausgabe in einer Form zurückgegeben, die du speichern oder abrufen kannst – die genaue Antwortstruktur und die unterstützten Parameter findest du in der Endpunktreferenz. Betrachte diese Referenz als einzige verbindliche Quelle für Feldnamen, akzeptierte Bildformate und Größenbeschränkungen, da sich diese Details unabhängig von diesem Dokument weiterentwickeln können.
Typische Anwendungsfälle sind die Retusche von Produktfotos, der Austausch von Hintergründen, Stilanpassungen sowie lokale Bearbeitungen, bei denen eine vollständige Neugenerierung des Bildes die Detailtreue verlieren würde. Wenn deine Aufgabe darin besteht, allein aus Text zu generieren statt zu bearbeiten, ist dieser Endpunkt nicht das richtige Werkzeug; verwende stattdessen ein Text-to-Image-Modell.
Eine Erwartung, die du früh etablieren solltest: Bearbeitung ist im Kern iterativ. Deine erste Anweisung trifft selten perfekt, daher solltest du deinen Workflow auf kostengünstige Iteration auslegen – ändere jeweils nur eine Variable, behalte das Referenzbild bei und vergleiche die Ausgaben, bevor du den nächsten Schritt gehst.
Woraus eine funktionierende Anfrage besteht
Bevor du Code schreibst, verschaffe dir Klarheit darüber, welche Eingaben eine Anfrage benötigt. Jeder Aufruf von fibo-edit-1.5/image-to-image kombiniert vier Arten von Informationen.
Authentifizierung
Alle Anfragen laufen über die einheitliche HiAPI-Schnittstelle und tragen deinen API-Schlüssel im Authorization-Header. Bewahre den Schlüssel in einer Umgebungsvariable auf, nicht im Quellcode, und committe ihn niemals.
Referenzbild
Du musst das Quellbild bereitstellen, auf das sich die Bearbeitung bezieht. Es gibt zwei gängige Formen: eine öffentliche URL, die der Dienst abrufen kann, oder base64-kodierte Daten, die in den JSON-Anfragekörper eingebettet sind. URLs erleichtern die Iteration; base64 vermeidet die Abhängigkeit von externem Hosting. In der Endpunktreferenz erfährst du, welche Formen akzeptiert werden und ob es Einschränkungen bei Abmessungen oder Auflösung gibt.
Bearbeitungsanweisung
Dies ist eine Zeichenkette in Alltagssprache, die die Änderung beschreibt. Formuliere sie im Imperativ, benenne den Bereich oder das Element, das geändert werden soll, und gib an, was erhalten bleiben soll. Vermeide es, mehrere unzusammenhängende Bearbeitungen in eine einzige Anweisung zu packen – teile sie in mehrere Aufrufe auf, damit du erkennen kannst, welche davon ein schlechtes Ergebnis verursacht hat.
Ausgabesteuerung
Optionale Stellschrauben wie Abmessungen, Ausgabeformat oder Anzahl der Kandidatenbilder. Belasse sie beim ersten Aufruf auf den Standardwerten und passe sie erst später bewusst an. Jeder Parameter, den du setzt, ist eine weitere Variable, die du bei Problemen ausschließen musst.
Ein minimaler Anfragekörper hat also zwei wesentliche Felder – Bild und Anweisung –, verpackt in ein JSON-Objekt, optional ergänzt um deine Ausgabevorlieben. Wenn du die Frage „Welches Bild, welche Änderung, in welchem Format soll ich es zurückbekommen?“ beantworten kannst, hast du alles, was du zum Schreiben des Aufrufs brauchst.
Aufruf mit curl
Beginne mit curl: Es isoliert die HTTP-Ebene, sodass du bei Problemen weißt, dass sie in der Anfrage und nicht im Anwendungscode liegen.
Exportiere zunächst deinen Schlüssel:
export HIAPI_API_KEY="your-api-key"
Sende dann einen JSON-Anfragekörper mit Referenzbild-URL und Anweisung:
curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/input.jpg",
"prompt": "Ersetze den eintönigen Himmel durch einen sanften Sonnenuntergangsverlauf; lasse Gebäude und Vordergrund unverändert."
}'
Ein paar praktische Hinweise:
- Überprüfe Basis-URL und Pfad anhand der Endpunktreferenz und kopiere sie nicht aus dem Gedächtnis.
- Verwende
-sS, damit curl bei Erfolg still bleibt, aber Übertragungsfehler dennoch anzeigt. - Wenn du nicht von externem Hosting abhängig sein willst, kodiere die Datei mit base64 und ersetze den Wert von
imagedurch die kodierte Zeichenkette – mit dem in der Referenz angegebenen Feldnamen. - Leite die Ausgabe in der Erkundungsphase durch
jq ., damit die Antwort lesbarer wird.
Um die Antwort zu prüfen, suche nach der zurückgegebenen Bildnutzlast oder URL und öffne sie. Wenn der Antwortkörper stattdessen ein Fehlerobjekt enthält, notiere die Felder type und message – sie sagen dir, ob das Problem beim Bild, bei der Anweisung oder beim Aufbau der Anfrage liegt. Speichere eine erfolgreiche Rohantwort in einer Datei; sie wird zum Test-Fixture, wenn du den Python-Client schreibst, und zum Beleg, falls sich das Verhalten später ändert.
Dieselbe Anfrage mit Python senden
Die Python-Version sollte mit dem curl-Aufruf exakt übereinstimmen – gleicher Pfad, gleiche Header, gleicher Anfragekörper –, damit jede Abweichung ein Fehler in deinem Code ist und nicht in dem, was du anforderst.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"
payload = {
"image": "https://example.com/input.jpg",
"prompt": (
"Ersetze den eintönigen Himmel durch einen sanften Sonnenuntergangsverlauf; "
"lasse Gebäude und Vordergrund unverändert."
),
}
response = requests.post(
URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)
Eine lokale Datei senden
Wenn du eine Datei auf der Festplatte bearbeitest, kodiere sie und sende die Zeichenkette statt einer URL:
import base64
with open("input.jpg", "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
payload = {
"image": encoded,
"prompt": "Ändere den Hintergrund zu einem sauberen, neutralen Grau; halte das Produkt scharf.",
}
Bevor du dich auf diese Methode verlässt, verifiziere den genauen Feldnamen und die erwartete Kodierung in der Endpunktreferenz.
Ausgaben speichern
Schreibe die zurückgegebenen Bilder auf die Festplatte, damit du Iterationsergebnisse nebeneinander vergleichen und festhalten kannst, welche Anweisung welches Ergebnis erzeugt hat. Eine kleine Hilfsfunktion, die Ausgaben unter einem aus einem Hash der Anweisung abgeleiteten Namen speichert, macht spätere Vergleiche zum Kinderspiel.
Setze unbedingt ein explizites timeout. Bildbearbeitung dauert länger als einfache Textaufrufe, und Anfragen ohne Timeout lassen Arbeitsprozesse bei Netzwerkstillständen unbegrenzt hängen.
Fehler behandeln und sicher wiederholen
Fehlschläge lassen sich in einige wenige Kategorien einteilen, von denen jede eine andere Reaktion erfordert.
Client-Fehler
Die Anfrage selbst ist fehlerhaft: fehlerhaftes JSON, fehlendes Bildfeld, nicht unterstütztes Bildformat, eine Anweisung, die das Modell nicht ausführen kann, oder ein Authentifizierungsproblem. Solche Fehler unverändert zu wiederholen kostet nur Zeit und Kontingent – sie werden auf genau dieselbe Weise fehlschlagen. Korrigiere stattdessen die Anfrage. Bei solchen Fehlern protokolliere den vollständigen Anfragekörper (Bildteil gekürzt) und die Fehlermeldung und korrigiere dann die Eingabe.
Ratenbegrenzung
Du sendest Anfragen schneller, als es erlaubt ist. Die richtige Reaktion ist Zurückhaltung und erneuter Versuch, nicht das Bombardieren des Endpunkts. Befolge alle Hinweise zum erneuten Versuch aus der Antwort; andernfalls verwende exponentielles Backoff.
Server- und transiente Fehler
Timeouts, Verbindungsabbrüche und Upstream-Störungen sind einen erneuten Versuch wert. Hier kommt idempotente Wiederholungslogik ins Spiel.
Praktische Wiederholungsstrategie
- Wiederhole nur bei Timeouts, Verbindungsfehlern sowie Ratenbegrenzungs- oder Serverantworten.
- Verwende exponentielles Backoff mit Obergrenze – beginne zum Beispiel mit einer kurzen Verzögerung, verdopple sie bei jedem Versuch und stoppe nach wenigen festen Versuchen.
- Füge Jitter zur Verzögerung hinzu, damit parallele Arbeitsprozesse nicht alle im selben Moment erneut versuchen.
- Wiederhole niemals Anfragen, die wegen Schema-, Format- oder Anweisungsproblemen abgelehnt wurden.
- Protokolliere jeden Versuch mit Versuchsnummer und Ergebnis, damit du erkennst, ob sich Fehler häufen.
import random, time, requests
def edit_with_retry(payload, attempts=4):
delay = 1.0
for i in range(attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
except (requests.Timeout, requests.ConnectionError):
pass
else:
if r.status_code < 400:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
r.raise_for_status()
time.sleep(delay + random.uniform(0, 0.5))
delay = min(delay * 2, 30)
raise RuntimeError("Bearbeitung ist auch nach Wiederholungen fehlgeschlagen")
Betrachte dies als Gerüst: Gleiche die wiederholbaren Statuscodes mit dem ab, was der Endpunkt tatsächlich zurückgibt, und bündle die Strategie an einer Stelle, damit alle Aufrufer sie gemeinsam nutzen.
Prüfungen vor dem Go-live
Bevor du den Endpunkt in die Produktion bringst, arbeite eine kurze Checkliste ab.
Verifiziere den Normalfall zweimal
Führe deinen gespeicherten curl-Aufruf und den Python-Client mit denselben Eingaben erneut aus und stelle sicher, dass sie äquivalente Ergebnisse liefern. Wenn sie voneinander abweichen, sind deine Anfragekörper in Wahrheit nicht identisch.
Kalibriere Anweisungen an echten Eingaben
Teste deine Anweisungen mit repräsentativen Bildern, nicht nur mit einem einzelnen Exemplar. Die Bearbeitungsqualität hängt stark davon ab, wie konkret die Anweisung ist und wie gut das Referenzbild die Änderung unterstützt. Halte eine kleine Sammlung von Prompt-Ausgabe-Paaren als Regressions-Testsuite bereit; wenn du Formulierungen anpasst, kannst du erkennen, welche Verbesserungen und welche Rückschritte bringen.
Prüfe Grenzen und Formate
Bestätige in der Endpunktreferenz die akzeptierten Bildformate, die maximalen Abmessungen und etwaige Obergrenzen für die Anfragegröße. Validiere lokal vor dem Senden – ein schlechtes Bild im Client abzulehnen ist schneller und günstiger als ein Roundtrip.
Verifiziere Schlüssel und Logs
Stelle sicher, dass der API-Schlüssel aus einer Umgebungsvariable stammt, dass Anfrage-Logs die Bildnutzlast kürzen und dass kein Schlüssel in Fehlerberichten erscheint.
Bestätige das Fehlerverhalten
Erzwinge in einer Staging-Umgebung einmal einen Timeout und einen fehlerhaften Anfragekörper, prüfe, ob deine Wiederholungsstrategie korrekt handelt und ob dauerhafte Fehler an den Aufrufer durchgereicht werden, statt stillschweigend zu verschwinden.
Sobald all dies besteht, wird die Integration auf die beste Art unspektakulär. Hole dir die verbindliche Parameterliste aus der Referenz zum Image-to-Image-Endpunkt von fibo-edit-1.5 und baue dann von einem funktionierenden curl-Aufruf aus weiter.
Ä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