So verwenden Sie die FLUX.1 Fill Pro API: Mask Inpainting mit curl und Python

flux-1-fill-pro ist das maskenbasierte Inpainting-Modell von hiapi: Sie senden ein Quellbild, eine Schwarzweiß-Maske und einen Prompt, und nur die weißen Bereiche werden neu gezeichnet. Diese Anleitung enthält funktionsfähige curl- und Python-Anfragen, den asynchronen Ablauf und die Ergebnisse eines echten Laufs in Bezug auf Maskengrenzen und Ausgabegröße. Sie benötigen einen API-Schlüssel vom Dashboard.

Anfragestruktur

Das Modell läuft auf der einheitlichen Task-API. Erstellen Sie eine Aufgabe mit POST https://api.hiapi.ai/v1/tasks, fragen Sie GET /v1/tasks/<taskId> ab und lesen Sie dann data.output[0].url. Die folgenden Eingaben stammen von der Modellseite und der API-Dokumentation:

Feld	Typ	Beschreibung
input.image	URL, erforderlich	Quellbild. JPEG, PNG, GIF oder WebP.
input.mask	URL, erforderlich	Schwarz behält das Quellbild bei, Weiß wird neu gezeichnet. Muss dieselben Abmessungen wie das Quellbild haben.
input.prompt	string, erforderlich	Beschreibt den neuen Inhalt in den weißen Bereichen. Maximal 4.000 Zeichen.
input.steps	int, 15–50	Standard 50.
input.guidance	number, 1.5–100	Standard 60.
input.seed	int	Bei gleichen Eingaben liefert ein fester Seed konsistente Ergebnisse.
input.output_format	jpg | png	Standard jpg.
input.prompt_upsampling	bool	Standard false. Lassen Sie es deaktiviert, um Ihre genaue Formulierung beizubehalten.

image und mask sind beide URLs, kein base64 und kein Datei-Upload. Hosten Sie sie an einem Ort, der für die API über http(s) erreichbar ist.

Minimale curl-Anfrage

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-fill-pro",
    "input": {
      "image": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418738578-4e5072a121d7018f-source.jpg",
      "mask": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418739459-82bb18075f29c864-mask.png",
      "prompt": "Ein großformatiges Ölgemälde einer nebligen Berglandschaft mit See im Morgennebel, mit schmalem schwarzem Rahmen, flach an der Wand hängend; Sofa, Boden und Beleuchtung unverändert lassen.",
      "steps": 30,
      "guidance": 60,
      "seed": 42,
      "output_format": "png"
    }
  }'

Die Antwort ist {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}. Fragen Sie diese ID ab, bis data.status success oder fail ist.

Python: Erstellen, Abfragen, Herunterladen

import os, time, requests

API = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def inpaint(image_url, mask_url, prompt, **opts):
    body = {"model": "flux-1-fill-pro",
            "input": {"image": image_url, "mask": mask_url, "prompt": prompt, **opts}}
    r = requests.post(f"{API}/v1/tasks", headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:
        try:
            d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=20).json()["data"]
        except requests.RequestException:
            time.sleep(5)          # transient network error: poll the same taskId again
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error", d))
        time.sleep(5)

url = inpaint(
    "https://example.com/room.jpg",
    "https://example.com/room-mask.png",
    "Ein gerahmtes Landschaftsgemälde mit schmalem schwarzem Rahmen; den Raum unverändert lassen.",
    steps=30, seed=42, output_format="png",
)
open("out.png", "wb").write(requests.get(url, timeout=60).content)

Laden Sie das Ergebnis sofort herunter. Die Ausgabe-URL hat ein expireAt, und die Dateien werden nur temporär gespeichert; speichern Sie den Link daher nicht als dauerhafte Adresse.

Hinweise für den Produktivbetrieb

• Polling oder Callback. Fügen Sie für Stapelaufgaben dem Task-Body "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"} hinzu und deduplizieren Sie Benachrichtigungen anhand der Task-ID. Behalten Sie das Polling als Fallback bei.
• Wiederholen Sie das Polling, nicht das Erstellen. Ein neues POST erstellt und berechnet eine neue Aufgabe. Wenn eine Polling-Anfrage fehlschlägt, fragen Sie dieselbe taskId erneut ab.
• Maske und Quellbild konsistent halten. Die Maske muss exakt dieselben Abmessungen wie das Quellbild haben; erzeugen Sie sie daher aus derselben Datei (Polygon-Werkzeug, Segmentierungsausgabe) und nicht durch Skalieren eines Screenshots.
• Seed beim Abstimmen fixieren. Verwenden Sie denselben Seed und ändern Sie nur steps oder guidance, sodass jeder Unterschied von diesem Parameter stammt.

Die Kosten pro Bild finden Sie auf der Preisseite; prüfen Sie diese, bevor Sie große Materialmengen verarbeiten.

Was ein echter Lauf gezeigt hat

Ich habe die obige curl-Anfrage einmal mit dem Beispielraumfoto dieser Seite (1600×900) und seiner rechteckigen Maske (weißer Kasten bei x 840–1240, y 160–580) ausgeführt. Einstellungen: steps: 30, guidance: 60, seed: 42, output_format: png.

• Dauer. Die Aufgabe war etwa 25 Sekunden im Status handling, dann archiving, und erreichte nach insgesamt etwa 38 Sekunden success.
• Ausgabegröße weicht vom Quellbild ab. Das zurückgegebene PNG war 1440×810 statt 1600×900. Das Seitenverhältnis stimmt, die Pixelabmessungen nicht. Wenn Sie das Ergebnis zurück in das Originalbild komponieren möchten, skalieren Sie zuerst eines der beiden und gehen Sie nicht von 1:1 aus.
• Außerhalb der Maske unverändert. Nach Skalierung des Quellbilds auf 1440×810 und Differenzbildung mit der Ausgabe änderten sich 81 % der Pixel innerhalb des weißen Kastens um mehr als 8 Stufen (0–255), außerhalb des Kastens jedoch nur 0,03 % der Pixel. Mehr als 12 px vom Maskenrand entfernt betrug der maximale Unterschied 11 Stufen. Sofa, Kissen, Pflanze, Boden und Fensterlicht wurden nicht neu gezeichnet.
• Umfang des Prompts. Der Prompt beschrieb nur das Gemälde und die beizubehaltenden Inhalte; das Ergebnis war eine gerahmte Bergsee-Szene, die den weißen Kasten ausfüllte.
• Falsche URLs schlagen beim Polling fehl, nicht beim Erstellen. Eine weitere Anfrage, bei der image und mask auf Nicht-URL-Strings gesetzt waren, gab 200 und eine taskId zurück; anschließend endete die Aufgabe nach etwa 3 Sekunden mit status: fail und error.code: TASK_FAILED. Ein erfolgreiches POST bedeutet nicht, dass die Eingaben gültig sind; prüfen Sie daher immer den Endstatus.

Nicht getestet: nicht übereinstimmende Abmessungen von Maske und Quellbild, Masken mit Grauwerten (weiche Kanten), Masken mit Alphakanal sowie Extremwerte für guidance oder steps. Die Dokumentation verlangt, dass die Maske zu den Abmessungen des Quellbilds passt, und ich habe nur harte binäre Rechtecke getestet. Ich habe nicht mehrere Seeds ausgeführt und kann daher nicht sagen, wie stark die Füllung zwischen den Läufen variiert.

Wann Sie Fill Pro wählen sollten

Verwenden Sie es, wenn die Bearbeitung an harten, von Ihnen kontrollierten Grenzen enden muss, etwa bei Produktetiketten, Wandlinien oder Kleidungsnähten. Für Bearbeitungen, die durch Text beschrieben werden und keine Maske benötigen, verwenden Sie ein reines Prompt-Modell. Der Leitfaden zu Bild-Inpainting und Objektentfernung vergleicht sie. Wenn Sie etwas aus einer Maske löschen möchten, ohne einen Prompt zu schreiben, lesen Sie den Bria Eraser-Leitfaden.

Verwandtes

• FLUX.1 Fill Pro Modellseite
• flux-1-fill-pro API-Referenz
• Preise
• So verwenden Sie die Bria Eraser API
• Leitfaden zu FLUX.2 Image-to-Image

Häufig gestellte Fragen

Sind image und mask beide erforderlich?

Ja. Die aktuelle Dokumentation führt image, mask und prompt als erforderlich auf.

Welche Farbe zeichnet das Modell neu?

Weiß. Schwarze Pixel behalten das Quellbild bei.

Muss die Maske dieselben Abmessungen wie das Quellbild haben?

Die Dokumentation sagt das. In meinem Lauf habe ich ein passendes Paar verwendet und den Fall nicht übereinstimmender Abmessungen nicht getestet.

Wie sieht die Ausgabegröße aus?

In meinem Lauf lieferte ein Quellbild mit 1600×900 ein PNG mit 1440×810 bei gleichem Seitenverhältnis.