Tutorial
flux-2/image-to-image über die HiAPI API verwenden: curl- und Python-Tutorial
Auf dieser Seite
Was flux-2/image-to-image leistet und wofür es geeignet ist
flux-2/image-to-image ist ein Bearbeitungs-Endpunkt, kein reiner Text-zu-Bild-Generator. Du übergibst ihm zwei Dinge: ein Referenzbild und eine in natürlicher Sprache verfasste Bearbeitungsanweisung. Das Modell liest das Referenzbild als visuellen Kontext – Motiv, Komposition, Stil, Beleuchtung – und erzeugt ein neues Bild, das deiner Anweisung folgt und zugleich an diesem Referenzbild verankert bleibt.
Bei der Gestaltung einer Pipeline ist dieser Unterschied wichtig. Bei Text-zu-Bild beschreibst du alles von Grund auf und hoffst, dass das Modell in die Nähe deiner Absicht gelangt. Bei Bild-zu-Bild hast du bereits ein visuelles Ausgangsmaterial und willst eine kontrollierte Transformation: das Produktbild stilistisch neu gestalten, den Hintergrund ersetzen, die Stimmung einer Szene anpassen oder ein Design iterieren, während die zugrunde liegende Komposition stabil bleibt.
Geeignete Szenarien
- Varianten eines Ausgangsmaterials. Ausgehend von einem bereits abgenommenen Referenzbild mehrere stilisierte Bearbeitungen erzeugen.
- Geführte Bearbeitung. Gezielte Änderungen anwenden („das Licht wärmer machen“, „den Hintergrund durch eine einfarbige Studio-Wand ersetzen“), ohne die ganze Szene neu zu generieren.
- Konsistenz innerhalb einer Ergebnisgruppe. Dasselbe Referenzbild wiederverwenden, damit eine Reihe von Ausgaben denselben visuellen Anker teilt.
- Tools für die Mensch-Maschine-Zusammenarbeit. Nutzer laden ein Bild hoch, beschreiben eine Änderung und erhalten das Ergebnis in deiner eigenen Oberfläche zurück.
Ungeeignete Szenarien
- Pixelgenaue Retusche oder Komposition. Dies ist ein generatives Modell, kein Rasterbild-Editor.
- Fälle ganz ohne Referenzbild – hier ist Text-zu-Bild der bessere Ausgangspunkt.
- Jeder Workflow, bei dem allein die Anweisung sämtliche Details tragen soll; das Referenzbild wirkt tatsächlich mit, und ein schlechtes Referenzbild erzeugt nur schlechte Ergebnisse.
Verstehe diesen Endpunkt als Referenzbild + Anweisung -> bearbeitetes Bild. Alles in diesem Tutorial baut auf dieser Form auf: wie du sendest, wie du das zurückgegebene Ergebnis liest und wie du es am Laufen hältst, wenn das Netz nicht mitspielt.
Voraussetzungen und Authentifizierung einrichten
Vor dem ersten Aufruf brauchst du drei Dinge.
1. Ein HiAPI-Konto
Registriere dich und öffne die Konsole. Alle Anfragen in diesem Tutorial gehen über die einheitliche HiAPI-API, sodass du weder separate Anbieterkonten anlegen noch pro Anbieter ein SDK installieren musst.
2. Ein API-Schlüssel
Erstelle in der Konsole einen API-Schlüssel. Behandle ihn wie ein Passwort: nicht in ein Repository committen, nicht in Client-Code einbetten und nicht in Logs schreiben. Übliche Praxis ist das Laden zur Laufzeit aus einer Umgebungsvariable:
export HIAPI_API_KEY="your-api-key-here"
Verweise dann überall dort, wo der Schlüssel benötigt wird, auf HIAPI_API_KEY. Wenn du in einen Container oder auf eine serverlose Plattform deployst, setze ihn dort als Secret in der Umgebung und backe ihn nicht ins Image ein.
3. Ein erreichbares Referenzbild
Der Endpunkt benötigt ein Referenzbild, also entscheide vorab, wie du es bereitstellst. Zwei gängige Wege:
- Eine URL, die die API abrufen kann, etwa ein signierter Link auf deinen eigenen Objektspeicher.
- Base64-kodierte Bytes, die inline im Anfragekörper gesendet werden; das vermeidet das Offenlegen interner URLs, vergrößert aber die Nutzlast.
Wähle zunächst ein kleines Testbild – ein paar hundert KB reichen aus, um die Integration zu prüfen. Große Uploads verlangsamen jeden Wiederholungsversuch und erschweren das Debuggen.
Checkpoint
Du solltest jetzt einen in einer Umgebungsvariable abgelegten Schlüssel und ein von deinem Rechner aus erreichbares Testbild haben. Halte den Schlüssel möglichst aus der Shell-Historie heraus (eine von Tools geladene .env-Datei ist meist sauberer als ein Inline-Export auf der Kommandozeile).
Noch eine Angewohnheit, die du dir von Anfang an zulegen solltest: protokolliere ab dem ersten Tag Request-IDs und Laufzeiten. Wenn in der Produktion etwas schiefgeht, ist der Unterschied zwischen einer nachvollziehbaren und einer nicht nachvollziehbaren Anfrage enorm.
Die Anfrage aufbauen: Referenzbild und Bearbeitungsanweisung
Jeder Bild-zu-Bild-Aufruf baut auf zwei Eingaben auf. Wenn diese beiden stimmen, ist der Rest reine Infrastrukturarbeit.
Eingabe eins: das Referenzbild
Das Referenzbild ist der Anker. Es sagt dem Modell, was die Szene vor jeder Bearbeitung enthält und wie sie aussieht. Praktische Hinweise:
- Passe das Seitenverhältnis an die gewünschte Ausgabe an. Ist das Referenzbild ein breites Querformat, du aber brauchst eine quadratische Ausgabe, rechne je nach Konfiguration des Aufrufs mit Beschnitt oder Verzerrung.
- Beginne mit einem sauberen, gut ausgeleuchteten Bild. Ein trübes Referenzbild erzeugt trübe Bearbeitungsergebnisse.
- Am besten genau ein klar erkennbares Motiv. Eine unübersichtliche Collage gibt dem Modell zu viele konkurrierende Anker.
Eingabe zwei: die Bearbeitungsanweisung
Die Anweisung ist die natürlichsprachliche Beschreibung der gewünschten Änderung. Hier entsteht der größte Teil der Qualitätsunterschiede. Behandle sie als Prompt, der ein Referenzbild mitbringt.
- Benenne die Änderung, nicht die ganze Szene. „Den Hintergrund durch eine rein weiße Studio-Wand ersetzen“ ist besser als „Produkt auf weißem Hintergrund“ – Letzteres verleitet das Modell, alles neu zu malen.
- Sage, was erhalten bleiben muss. Formulierungen wie „die Pose und die Komposition des Motivs unverändert lassen“ reduzieren Drift deutlich.
- Beschreibe Stil und Licht konkret. „Weiches, bedecktes Licht, entsättigte Farben“ gibt dem Modell mehr verwertbare Information als „mach es schöner“.
- Vermeide Widersprüche. Wenn das Referenzbild eine Außenszene bei Tag zeigt und du einen nächtlichen Innenraum verlangst, rechne mit einer Entscheidung des Modells, die dir vielleicht nicht gefällt.
Der Anfragekörper
Deine Anfrage an flux-2/image-to-image enthält die Modellkennung, das Referenzbild und die Anweisung. Ein nützliches mentales Modell:
{
"model": "flux-2/image-to-image",
"input": {
"image": "<URL oder base64-Referenzbild>",
"prompt": "<Bearbeitungsanweisung>"
}
}
Wenn dein Referenzbild base64 ist, baue es gemäß dem Anfrage-Schema als Data-URI oder übergebe die rohe Kodierung zusammen mit dem MIME-Typ. Bei einer URL stelle sicher, dass der Link während des Aufrufs öffentlich erreichbar ist – ein signierter Link, der mitten in der Anfrage abläuft, erzeugt schwer verständliche Fehler.
Erst iterieren, dann integrieren
Bevor du irgendetwas in Code gießt, schreibe zwei oder drei Anweisungen für dasselbe Referenzbild und vergleiche die Ausgaben. Bei konkreten Anweisungen verhält sich das Modell vorhersehbar; bei vagen ist es instabil; das jetzt zu lernen ist viel billiger als in der Produktion.
Eine funktionierende curl-Anfrage
Der schnellste Weg, Schlüssel, Referenzbild und Anweisung zu prüfen, ist ein curl-Aufruf. Das folgende Beispiel geht davon aus, dass dein Schlüssel in HIAPI_API_KEY liegt und das Referenzbild über eine URL erreichbar ist.
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/image-to-image",
"input": {
"image": "https://your-bucket.example.com/reference.jpg",
"prompt": "Den Hintergrund durch eine rein weiße Studio-Wand ersetzen. Pose, Komposition und die Beleuchtung auf dem Motiv unverändert lassen."
}
}'
Ein paar Punkte sind zu beachten:
- Der Schlüssel wird über den
Authorization-Header als Bearer-Token übertragen. Lege ihn niemals in die URL. Content-Typeist JSON. Ihn zu vergessen ist eine häufige Ursache für verwirrende 4xx-Fehler.- Die Modell-ID steht im Anfragekörper, sodass derselbe Endpunkt durch Ändern eines Felds auf andere Modelle geroutet werden kann.
- Die Anweisung ist ein vollständiger Satz, keine Stichwortliste. Das ist beabsichtigt – siehe voriger Abschnitt.
Die Rohausgabe lesen
Führe den Aufruf zunächst einmal aus und sieh dir die vollständige Antwort an, bevor du Auswertungscode schreibst. Bei Bedarf formatiere sie mit einem Tool:
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
Den Anfragekörper in einer Datei (request.json) abzulegen, erleichtert die Iteration gegenüber Shell-Strings mit Quoting und gibt dir ein dauerhaftes Artefakt, mit dem du später einen Bug reproduzieren kannst.
Wenn du base64 statt einer URL brauchst
Ersetze den Wert von image durch einen aus deiner Datei erzeugten Data-URI:
python - <<'PY'
import base64, json, pathlib
data = base64.b64encode(pathlib.Path("reference.jpg").read_bytes()).decode()
body = {
"model": "flux-2/image-to-image",
"input": {
"image": f"data:image/jpeg;base64,{data}",
"prompt": "Das Licht wärmer machen und den Kontrast etwas verringern.",
},
}
pathlib.Path("request.json").write_text(json.dumps(body))
PY
Jetzt funktioniert derselbe curl-Aufruf, weil die Nutzlast in request.json liegt. Wenn der Aufruf gelingt, hast du alles, was du für den Wechsel zu Python brauchst.
Derselbe Aufruf in Python
Die Python-Version bleibt bewusst schlicht: dasselbe Dictionary bauen, mit denselben Headern senden und Endpunkt und Modell in Konstanten ablegen, damit nichts gegenüber der curl-Version auseinanderläuft.
import os
import requests
API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "flux-2/image-to-image"
def edit_image(reference_url: str, instruction: str, timeout: float = 60.0) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # schlägt sofort fehl, wenn nicht gesetzt
payload = {
"model": MODEL,
"input": {
"image": reference_url,
"prompt": instruction,
},
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = edit_image(
"https://your-bucket.example.com/reference.jpg",
"Den Hintergrund durch eine rein weiße Studio-Wand ersetzen. "
"Pose, Komposition und die Beleuchtung auf dem Motiv unverändert lassen.",
)
print(result)
Warum es so aufgebaut ist
os.environ["HIAPI_API_KEY"]statt.get(), damit ein fehlender Schlüssel sofort einen Fehler auslöst, statt eine nicht authentifizierte Anfrage zu senden.timeoutist explizit. Bildgenerierung ist nicht instantan; Anfragen ohne Timeout blockieren am Ende einen Worker.raise_for_status()vor dem Auswerten aufrufen. Du willst bei 4xx oder 5xx eine Exception, nicht später irgendwo einen verwirrendenKeyError.- Endpunkt und Modell sind Konstanten auf Modulebene, wodurch es ein Leichtes ist, die Testsuite auf einen Stub-Server zu richten.
Base64-Eingabe verwenden
Wenn du Bytes statt einer URL übergibst, kodiere die Datei an derselben Stelle, an der du die Nutzlast baust, und erstelle den Data-URI:
import base64, pathlib
def as_data_uri(path: str, mime: str = "image/jpeg") -> str:
raw = pathlib.Path(path).read_bytes()
return f"data:{mime};base64," + base64.b64encode(raw).decode()
Rufe dann edit_image(as_data_uri("reference.jpg"), instruction) auf. Trenne den Kodierungsschritt von der Anfragefunktion, damit du Validierung und Prompt-Zusammenbau ohne Netzzugriff per Unit-Test prüfen kannst.
Die Antwort auswerten
Der Aufruf gibt ein JSON-Objekt zurück. Extrahiere nun das bearbeitete Bild so, dass selbst dann kein Fehler entsteht, wenn die Antwort künftig weitere Felder erhält.
Erst prüfen, nicht annehmen
Gib während der Entwicklung eine Rohantwort aus und achte darauf, wo der Bildverweis liegt – üblicherweise eine URL oder eine Base64-Nutzlast innerhalb der Ergebnisstruktur. Schreibe dann Accessor-Funktionen, die dessen Vorhandensein prüfen, statt direkt in verschachtelte Schlüssel zu greifen.
def extract_image_url(response: dict) -> str:
data = response.get("data") or []
if not data:
raise ValueError(f"Keine Bilddaten in der Antwort: {response}")
first = data[0]
url = first.get("url") or first.get("b64_json")
if not url:
raise ValueError(f"Unbekannte Bildnutzlast: {first}")
return url
Zwei Gewohnheiten aus diesem Code solltest du beibehalten: mit der tatsächlichen Nutzlast in der Fehlermeldung laut scheitern und beide Formen akzeptieren (URL oder base64), statt eine davon fest zu verdrahten. Antwortformate entwickeln sich weiter; ein toleranter Leser überlebt.
Sofort persistieren
Die zurückgegebene URL kann temporär sein. Wenn das Bild wichtig ist, lade es im selben Task herunter und lege es in deinem eigenen Bucket ab:
def persist(url: str, dest: str) -> None:
if url.startswith("data:"):
header, b64 = url.split(",", 1)
import base64, pathlib
pathlib.Path(dest).write_bytes(base64.b64decode(b64))
return
with requests.get(url, stream=True, timeout=60) as r:
r.raise_for_status()
with open(dest, "wb") as f:
for chunk in r.iter_content(1 << 16):
f.write(chunk)
Durch das Persistieren erhältst du zudem einen stabilen Schlüssel, den du in der Datenbank ablegen kannst – viel nützlicher als ein Link, der verrotten kann.
Prüfe, was du bekommen hast
Günstige Prüfungen decken teure Fehler auf. Stelle sicher, dass die Datei nicht leer ist, ihre Magic Number zu einem Bildformat passt und optional ihre Abmessungen den Erwartungen entsprechen. Eine beschädigte oder abgeschnittene Datei an der Grenze abzulehnen ist viel besser, als sie dem Nutzer vorzusetzen.
Herkunftsinformationen protokollieren
Speichere Modell-ID, Anweisungstext, Referenzbild-Schlüssel und Zeitstempel zusammen mit der Ausgabe. Wenn jemand drei Wochen später fragt, warum ein bestimmtes Bild so aussieht, ist diese Zeile die Antwort – und sie macht es ein Leichtes, eine bestimmte Bearbeitung erneut auszuführen.
Wiederholungen und Fehlerbehandlung in der Produktion
Bildgenerierungsaufrufe scheitern aus sehr unterschiedlichen Gründen, und sie alle über einen Kamm zu scheren ist ein klassischer Produktionsfehler.
Transiente von endgültigen Fehlern unterscheiden
- Transient – Timeouts, Verbindungsabbrüche, 429-Rate-Limits, 5xx-Antworten. Dieselbe Anfrage nach einer Pause zu wiederholen, wird wahrscheinlich gelingen.
- Endgültig – 400 ungültige Anfrage, 401 falscher oder fehlender Schlüssel, 404 unbekanntes Modell, Fehler bei der Nutzlastvalidierung. Diese zu wiederholen kostet Zeit und Geld und verzögert die eigentliche Fehlerbehebung.
Wiederhole nur die erste Kategorie. Bei der zweiten lasse den Task sofort scheitern und gib die Fehlermeldung aus – sie sagt dir fast immer genau, welches Feld das Problem ist.
Mit Backoff und Jitter wiederholen
import random, time, requests
RETRYABLE = {429, 500, 502, 503, 504}
def call_with_retries(fn, attempts: int = 5, base: float = 1.0):
last = None
for i in range(attempts):
try:
return fn()
except requests.HTTPError as e:
status = e.response.status_code if e.response is not None else None
if status not in RETRYABLE:
raise
last = e
except (requests.Timeout, requests.ConnectionError) as e:
last = e
delay = base * (2 ** i) + random.uniform(0, 0.5)
time.sleep(delay)
raise RuntimeError("Wiederholungsversuche erschöpft") from last
Exponentielles Backoff verhindert, dass du einen bereits angeschlagenen Dienst überrannt; Jitter verhindert, dass eine Charge von Workern synchron erneut versucht. Begrenze stets die Anzahl der Versuche und die Gesamtdauer – eine unbegrenzte Schleife ist schlimmer als ein sauberes Scheitern.
Rate-Limits respektieren
Bei einer 429-Antwort befolge vor dem Backoff alle Wiederholungshinweise in den Antwort-Headern. Wenn du große Stapel verarbeitest, füge auf deiner Seite eine Begrenzung der Nebenläufigkeit hinzu, statt dich darauf zu verlassen, dass der Server dich drosselt.
Fehler sichtbar machen
- Markiere Wiederholungen mit einer eindeutigen Task-ID und protokolliere jeden Versuch mit Ergebnis und Laufzeit.
- Erfasse Metriken zur Wiederholungsrate; ein langsamer Anstieg ist ein frühes Warnzeichen dafür, dass irgendwo upstream etwas schlechter wird.
- Nach dem letzten fehlgeschlagenen Versuch verschiebe den Task in eine Dead-Letter-Queue mit dem vollständigen Antwortkörper, niemals nur mit einer Meldung wie „failed“.
Idempotenz und Kostenvernunft
Eine wiederholte Anfrage kann auf dem Server bereits erfolgreich gewesen sein, auch wenn dein Client nie eine Antwort gesehen hat. Wenn dein Produkt doppelte Ausgaben nicht toleriert, schlüssele den Task mit deiner eigenen ID und gleiche vor dem Wiederholen ab. Und da Aufrufe nutzungsbasiert abgerechnet werden, hüte dich vor Wiederholungsschleifen, die die Kosten still in die Höhe treiben – ein Consumer, der hängt und ewig wiederholt, ist der teuerste Bug dieser Art.
Häufige Fallstricke und nächste Schritte
Die meisten Integrationsprobleme rund um flux-2/image-to-image stammen aus einer kleinen Reihe von Fehlern. Prüfe deinen Code vor dem Release anhand dieser Liste.
- Vage Anweisungen. „Verbessere es“ erzeugt zufällige Ergebnisse; „entferne den Text auf dem Schild und behalte die Form des Schilds bei“ erzeugt brauchbare Ergebnisse. Konkretheit ist der größte Hebel für Qualität.
- Unpassendes Referenzbild. Falsches Seitenverhältnis, unscharfes Ausgangsbild oder unübersichtliche Collage lassen sich nicht durch einen besseren Prompt retten.
- Abgelaufene URLs. Ein signierter Link, der mitten in der Anfrage abläuft, verursacht Fehler, die wie Serverfehler aussehen. Verwende eine ausreichend lange Gültigkeitsdauer oder base64.
- Fest verdrahtete Antwortstruktur. Direktes Zugreifen in verschachtelte Schlüssel macht aus einer kleinen Schemaänderung einen Ausfall. Nutze defensive Extraktoren mit klaren Fehlermeldungen.
- Fehlende Timeouts. Ein fehlendes Timeout belegt einen Worker unbegrenzt und verdeckt das eigentliche Problem.
- Endgültige Fehler wiederholen. Ein 400 löst sich nicht von selbst. Lies die Meldung.
- Verlorene Ausgaben. Wenn die zurückgegebene URL temporär ist und du das Bild nicht persistierst, hast du nichts.
- Unachtsames Loggen von Secrets und Prompts. Schlüssel dürfen niemals in Logs erscheinen; von Nutzern bereitgestellte Anweisungen müssen je nach deinem Anwendungsbereich möglicherweise redigiert werden.
Nächste Schritte
Wenn der Ablauf für einzelne Aufrufe stabil ist, sind die natürlichen Erweiterungen: den Aufruf als Hintergrundaufgabe kapseln, damit deine UI reaktionsfähig bleibt; Anweisungs-/Antwort-Paare speichern, um das Prompt-Formulieren per A/B-Test zu optimieren; und wenn Nutzer eigene Bilder bereitstellen, eine Prüf- oder Validierungsschicht auf die Eingaben legen. Sieh dir die Modellseite von flux-2/image-to-image und die HiAPI-Dokumentation an, um zu erfahren, welche Parameter dein Anwendungsfall als Nächstes brauchen könnte. Baue das kleinste funktionierende Ding, messe es und lass die Qualität der Anweisungen die Hauptarbeit tragen.
Ä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