Blog

Tutorial

So rufen Sie flux-1-fill-pro über die HiAPI API auf: curl, Python und asynchrones Polling

Nov 12, 2026
HiAPI-Blog-Titelbild: Auf dunkelindigoblauem Grund schreiten drei ineinander verschachtelte breite Pfeilformen horizontal stufenweise voran, die Vorderkanten in Aprikosenorange, im Stil eines flachen Signalflussdiagramms.
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 →

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