Tutorial
So rufen Sie flux-1-fill-pro über die HiAPI API auf: curl, Python und asynchrones Polling
Auf dieser Seite
Was flux-1-fill-pro leistet und wann Sie es einsetzen
flux-1-fill-pro ist ein Bildbearbeitungsmodell der Fill-Klasse. Sie übergeben ihm ein Quellbild und eine Maske, die den neu zu generierenden Bereich markiert, und es gibt ein neues Bild aus, in dem dieser Bereich ersetzt wurde. Bereiche außerhalb der Maske sollten unverändert bleiben – genau darin unterscheidet es sich von reinen Text-zu-Bild-Modellen oder Modellen zur Stilisierung des gesamten Bildes.
Setzen Sie es ein, wenn die Bearbeitung lokal begrenzt ist und der umgebende Kontext wichtig ist:
- Objektentfernung – markieren Sie unerwünschte Elemente mit der Maske und lassen Sie das Modell rekonstruieren, was hinter ihnen plausibel sein sollte.
- Objektauswechslung – grenzen Sie mit der Maske einen Bereich ein, beschreiben Sie den neuen Inhalt im Prompt und lassen Sie den Rest der Szene unverändert.
- Lokale Retusche – reparieren Sie Texturen, Reflexionen oder kleine Fehler, ohne das gesamte Bild neu zu generieren.
- Pipeline-Einschübe – reparieren Sie programmatisch Produktbilder, Thumbnails oder generierte Assets, bei denen nur ein Bereich eine zweite Bearbeitung benötigt.
Es ist nicht das richtige Werkzeug, wenn Sie eine völlig neue Komposition aus einem Prompt wünschen oder wenn Ihr Maskenbereich so groß ist, dass das Modell effektiv ein Bild von Grund auf generiert – in diesen Fällen verhält sich der Standard-Generierungs-Endpunkt vorhersehbarer.
Der Rest dieses Leitfadens behandelt, wie Sie flux-1-fill-pro über die HiAPI API in Code integrieren: Aufbau der Anfrage, curl-Aufruf, die Python-Entsprechung und die asynchrone Auftragsverarbeitung, die bei den meisten ersten Integrationen schiefgeht.
Vorbereitung und Einrichtung der Authentifizierung
Bevor Sie die erste Anfrage senden, bestätigen Sie drei Dinge.
API-Schlüssel
Erstellen Sie einen Schlüssel in Ihrem HiAPI-Konto und halten Sie ihn aus der Quellcodeverwaltung heraus. Die Beispiele unten lesen ihn aus einer Umgebungsvariable, sodass diese Snippets sicher kopiert werden können:
export HIAPI_API_KEY="your_key_here"
Laden Sie ihn in Python auf dieselbe Weise über os.environ. Wenn Sie in CI ausführen, injizieren Sie ihn als Secret, statt eine .env-Datei zu committen.
Modellbezeichner
Jede Anfrage benennt das Modell namentlich. In diesem Leitfaden lautet der Bezeichner flux-1-fill-pro. Halten Sie ihn als Konstante im Code, statt String-Literale zu verstreuen – so erfordert ein späterer Modellwechsel nur eine Zeile.
Basis-URL
Alle Aufrufe gehen an die HiAPI-API-Basis-URL, die in der Plattformreferenz dokumentiert ist. Bewahren Sie sie zusammen mit dem Schlüssel in Ihrer Konfiguration auf, sodass Staging und Produktion ohne Codeänderung unterschiedlich sein können.
Eine strukturelle Erinnerung vorab: Fill-Anfragen tragen Bilddaten. Senden Sie die Bilder base64-kodiert als JSON, statt zu versuchen, sie über einen Formular-Upload durchzudrücken; und halten Sie das Request-Timeout Ihres Clients großzügig – das Kodieren großer Bilder erhöht die Latenz, bevor die Anfrage Ihren Prozess überhaupt verlässt. Prüfen Sie die Plattformdokumentation auf die aktuellen Größenbeschränkungen für die Nutzlast; wenn Ihr Quellbild das dokumentierte Limit überschreitet, verkleinern Sie es vor der Kodierung, statt die Anfrage am Rand scheitern zu lassen.
Aufbau einer Inpainting-Anfrage
Jeder flux-1-fill-pro-Aufruf hat denselben logischen Aufbau, egal in welcher Sprache er geschrieben ist.
Quellbild
Das Bild, das Sie bearbeiten, kodiert als String. Es definiert die Leinwand: seine Abmessungen bestimmen den Koordinatenraum, in dem die Maske liegt, und sein Inhalt liefert dem Modell den Kontext, der die Füllung glaubwürdig macht.
Maske
Die Maske markiert, welche Bereiche neu generiert werden. Dies ist die häufigste Verwechslungsquelle, daher machen Sie sich klar, welche Konvention Ihre Nutzlast verwendet: Die maskierten Bereiche sind die Bereiche, die das Modell ändern darf. Bauen Sie die Maske als separates Bild, in dem der zu füllende Bereich und der zu erhaltende Bereich visuell klar unterscheidbar sind. Das Invertieren der Maske ist der klassische Bug – Sie erhalten ein Ergebnis, bei dem das Modell alles außer dem gewünschten Bereich bearbeitet hat.
Die Maske muss exakt dieselben Abmessungen wie das Quellbild haben. Eine Maske, die in einer anderen Auflösung gezeichnet wurde, wird entweder abgelehnt oder stillschweigend falsch ausgerichtet, und beides kostet Sie einen Roundtrip.
Prompt
Eine textliche Beschreibung dessen, was innerhalb der Maske erscheinen soll. Bleiben Sie konkret und lokal: Beschreiben Sie den Inhalt und seine Beziehung zur Umgebung in Bezug auf Licht oder Textur, nicht die gesamte Szene. „Eine Holzbank, die die Verkleidung des Ladenlokals fortsetzt, weiches Nachmittagslicht von links“ gibt dem Modell mehr Anhaltspunkte als „ein schönerer Hintergrund“.
Optionale Steuerparameter
Je nach dokumentiertem Parametersatz können Sie möglicherweise auch einen Seed für Reproduzierbarkeit oder einen stärkeartigen Parameter übergeben, der steuert, wie stark die Füllung von den ursprünglichen Pixeln abweichen darf. Behandeln Sie Parameter, die in der aktuellen Referenzdokumentation nicht existieren, als nicht unterstützt, statt ihre Namen zu raten.
Diese vier – Modell, Prompt, Quellbild, Maske – werden alle im selben JSON-Body übergeben. Die nächsten beiden Abschnitte senden genau diesen Body.
Eine funktionierende curl-Anfrage
Beginnen Sie mit curl, damit Sie den rohen Envelope sehen, bevor eine Clientbibliothek ihn verdeckt.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json
Dabei sieht request.json so aus:
{
"model": "flux-1-fill-pro",
"prompt": "Eine Holzbank, die die Verkleidung des Ladenlokals fortsetzt, weiches Nachmittagslicht von links",
"image": "<base64-encoded source image>",
"mask": "<base64-encoded mask image>"
}
Es gibt zwei praktische Tricks beim Bauen dieser Datei. Erstens: Erzeugen Sie die base64-Nutzlast mit Befehlen, statt sie manuell einzufügen:
base64 -w 0 source.png > source.b64
base64 -w 0 mask.png > mask.b64
Dann fügen Sie sie mit einem kurzen jq- oder Python-Schritt zusammen und bauen request.json. Das manuelle Einfügen mehrfach megabytegroßer base64-Blöcke in JSON ist genau die Ursache für abgeschnittene Nutzlasten und verwirrende 400-Fehler.
Die Antwort interpretieren
Der Antwort-Envelope sagt Ihnen, was als Nächstes zu tun ist. Abgeschlossene Aufträge liefern das bearbeitete Bild zurück – üblicherweise als URL oder base64-Feld, je nach dem in der aktuellen Referenz dokumentierten Format. In die Warteschlange gestellte Aufträge liefern einen Bezeichner und einen Status zurück, den Sie anschließend abfragen (siehe unten). Gehen Sie nicht davon aus, dass die erste Antwort immer Pixel enthält; schreiben Sie Ihren Parser von Anfang an so, dass er beide Formen verarbeitet, sonst müssen Sie ihn beim ersten Mal umschreiben, wenn Aufträge unter Last in die Warteschlange gestellt werden.
Prüfen Sie den HTTP-Statuscode, bevor Sie den Antwort-Body parsen. 4xx bedeutet, dass die Anfrage selbst fehlerhaft ist, und ein erneuter Versuch hilft nicht; korrigieren Sie stattdessen die Nutzlast.
Derselbe Aufruf in Python
Die Python-Version ist dieselbe Anfrage, nur bequemer zu handhaben. Kein SDK nötig – requests an den HiAPI-Endpunkt reicht aus.
import base64
import json
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "flux-1-fill-pro"
def b64(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("ascii")
def create_fill(source_path: str, mask_path: str, prompt: str) -> dict:
payload = {
"model": MODEL,
"prompt": prompt,
"image": b64(source_path),
"mask": b64(mask_path),
}
resp = requests.post(
f"{BASE_URL}/v1/images/edits",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(payload),
timeout=120,
)
if resp.status_code >= 400:
raise RuntimeError(f"HiAPI error {resp.status_code}: {resp.text}")
return resp.json()
Das timeout ist bewusst gesetzt. Das Kodieren und Hochladen großer Bilder dauert länger als ein typischer JSON-Aufruf, und unbegrenzte Anfragen sind genau der Grund, warum Skripte in Batch-Aufträgen stillschweigend hängen. Eine Exception bei 4xx mit dem Antwort-Body verwandelt mysteriöse Fehler in lesbare Fehler.
Halten Sie den Modellbezeichner und den Endpunkt in der Konfiguration auf Modulebene, sodass ein Versions-Upgrade nur eine Stelle betrifft. Wenn Sie viele Bilder verarbeiten, verwenden Sie eine wiederverwendete requests.Session, damit Verbindungen gepoolt werden, statt bei jedem Aufruf neu aufgebaut zu werden.
Das geparste Dictionary ist entweder ein abgeschlossenes Ergebnis oder ein Auftrags-Handle – der nächste Abschnitt behandelt Letzteres.
Asynchrone Aufträge und Polling behandeln
Fill-Anfragen können langsam sein, daher kann die API statt eines fertigen Bildes ein Auftrags-Handle zurückgeben. Das richtige Muster ist eine begrenzte Polling-Schleife, nicht ein festes sleep und dann beten.
Die Schleife
def wait_for_result(job: dict, *, interval=2.0, timeout=180.0) -> dict:
deadline = time.monotonic() + timeout
current = job
while time.monotonic() < deadline:
status = current.get("status")
if status in {"succeeded", "completed"}:
return current
if status in {"failed", "canceled", "cancelled"}:
raise RuntimeError(f"Job ended as {status}: {current}")
time.sleep(interval)
interval = min(interval * 1.5, 15.0) # sanftes Backoff
current = fetch_job(current["id"])
raise TimeoutError(f"Job {job.get('id')} exceeded {timeout}s")
fetch_job verwendet dasselbe Anfragemuster wie oben und greift mit der Auftrags-ID und Ihren Authentifizierungs-Headern auf den dokumentierten Auftragsstatus-Endpunkt zu.
Warum Backoff statt festem Intervall
Dichtes Polling einer Warteschlange hämmert unnötig auf die API, ohne etwas zu gewinnen. Mit einem kurzen Intervall zu beginnen und es bis zu einer Obergrenze zu multiplizieren, hält frühe Abschlüsse reaktionsschnell, ohne bei langsamen Aufträgen Tausende von Abfragen zu verschwenden. Setzen Sie eine Obergrenze für das Intervall, damit Sie einen Abschluss trotzdem innerhalb von Sekunden bemerken.
Warum Timeout und Fehler zwei verschiedene Dinge sind
Ein Timeout bedeutet, dass Sie aufgehört haben zu warten, nicht dass der Auftrag fehlgeschlagen ist. Behalten Sie die Auftrags-ID, wenn Sie die Exception werfen, damit der Aufrufer später das Polling fortsetzen kann, ohne erneut einzureichen und für dieselbe Arbeit doppelt zu bezahlen. Behandeln Sie in Ihrer Pipeline Timeouts, Auftragsfehler und HTTP-Fehler als drei verschiedene Exceptions – sie zu einem generischen Fehler zu verdichten, macht die Fehlersuche bei Produktionsvorfällen deutlich schwieriger.
Häufige Fehler debuggen
Die meisten Fehlerantworten fallen in einige wenige Kategorien. Prüfen Sie diese der Reihe nach.
401 / 403 – Authentifizierung
Prüfen Sie zuerst: Ist der Header genau Authorization: Bearer <key>, ohne Anführungszeichen und ohne überschüssige Leerzeichen aus einer nie exportierten Shell-Variable? Ein leeres $HIAPI_API_KEY erzeugt ein Bearer-Token, das nur aus dem Wort Bearer besteht, und schlägt genauso fehl wie ein falscher Schlüssel.
400 – Fehlerhafte Nutzlast
Prüfen Sie zuerst: Ist der Body nach dem Zusammenfügen der base64-Strings noch gültiges JSON? Geben Sie request.json aus und lassen Sie python -m json.tool darüber laufen. Ein data:image/png;base64,-Präfix an den Bildfeldern ist eine häufige Ursache – entfernen Sie es, sofern die Referenz es nicht ausdrücklich verlangt.
Maske/Bild stimmen nicht überein
Prüfen Sie zuerst: Haben Maske und Quellbild exakt dieselben Pixelabmessungen? Überprüfen Sie dann die Polarität – stellen Sie sicher, dass die weißen Bereiche die Bereiche sind, die das Modell neu generieren soll. Wenn das Ergebnis genau gegenteilig zu Ihrer Anforderung aussieht, ist fast immer die Maske invertiert und nicht der Prompt das Problem.
Prompt-Überlauf
Wenn sich nicht maskierte Bereiche verändern oder die Füllung global wirkt, ist Ihre Maske möglicherweise zu groß oder der Prompt zu sehr auf die gesamte Szene ausgerichtet. Verengen Sie beides: Ziehen Sie die Maske auf den tatsächlichen Bearbeitungsbereich fest und beschreiben Sie nur den Inhalt innerhalb der Maske.
Auftrags-Timeout
Prüfen Sie zuerst: die Nutzlastgröße. Übermäßig große Quellbilder sind die häufigste Ursache für Aufträge, die nie abgeschlossen werden. Verkleinern Sie das Bild, versuchen Sie es erneut, und wenn es weiterhin zu einem Timeout kommt, prüfen Sie mit einem kleinen Testbild gegen die Referenzgrenzen, bevor Sie ein Serviceproblem annehmen.
Ergebnisfeld leer oder fehlend
Prüfen Sie zuerst: Behandeln Sie die Form der Warteschlangenantwort? Ein Parser, der nur die abgeschlossene Form liest, sieht beim ersten Aufruf gar nichts. Protokollieren Sie während der Entwicklung den vollständigen Antwort-Envelope, damit Sie die Form sehen, bevor Sie defensiven Code schreiben.
Ä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