Come usare l'API FLUX.1 Fill Pro: inpainting con maschera tramite curl e Python

flux-1-fill-pro è il modello di inpainting basato su maschera di hiapi: invii un'immagine sorgente, una maschera in bianco e nero e un prompt, e solo le aree bianche vengono ridisegnate. Questa guida fornisce richieste curl e Python funzionanti, il flusso asincrono e ciò che una vera esecuzione ha mostrato in termini di bordi della maschera e dimensioni dell'output. È necessario ottenere una chiave API dalla dashboard.

Struttura della richiesta

Il modello gira sull'API unificata delle attività. Crea un'attività con POST https://api.hiapi.ai/v1/tasks, esegui il polling di GET /v1/tasks/<taskId>, poi leggi data.output[0].url. Gli input seguenti provengono dalla pagina del modello e dalla documentazione API:

Campo	Tipo	Descrizione
input.image	URL, obbligatorio	Immagine sorgente. JPEG, PNG, GIF o WebP.
input.mask	URL, obbligatorio	Il nero mantiene l'immagine sorgente, il bianco viene ridisegnato. Deve avere le stesse dimensioni dell'immagine sorgente.
input.prompt	string, obbligatorio	Descrive il nuovo contenuto all'interno delle aree bianche. Massimo 4.000 caratteri.
input.steps	int, 15–50	Predefinito 50.
input.guidance	number, 1.5–100	Predefinito 60.
input.seed	int	Con gli stessi input, un seed fisso produce risultati consistenti.
input.output_format	jpg | png	Predefinito jpg.
input.prompt_upsampling	bool	Predefinito false. Mantienilo disattivato per conservare la tua formulazione esatta.

image e mask sono entrambi URL, non base64 né upload di file. Ospitali in un luogo accessibile all'API via http(s).

Richiesta curl minima

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": "Un grande dipinto paesaggistico a olio di un lago montano nebbioso nella nebbia mattutina, con una sottile cornice nera, appeso uniformemente alla parete; mantieni invariati il divano, il pavimento e l'illuminazione.",
      "steps": 30,
      "guidance": 60,
      "seed": 42,
      "output_format": "png"
    }
  }'

La risposta è {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}. Esegui il polling di quell'ID finché data.status non diventa success o fail.

Python: creazione, polling, download

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",
    "Un dipinto paesaggistico incorniciato con una sottile cornice nera; mantieni invariata la stanza.",
    steps=30, seed=42, output_format="png",
)
open("out.png", "wb").write(requests.get(url, timeout=60).content)

Scarica il risultato immediatamente. L'URL di output contiene un expireAt e i file sono archiviati temporaneamente, quindi non salvare quel link come indirizzo permanente.

Considerazioni per la produzione

• Polling o callback.Per i lotti, aggiungi "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"} nel body dell'attività e deduplica le notifiche usando l'ID dell'attività. Mantieni il polling come piano di riserva.
• Riprova il polling, non la creazione.Un nuovo POST crea e fattura una nuova attività. Se una richiesta di polling fallisce, esegui di nuovo il polling dello stesso taskId.
• Mantieni la maschera coerente con la sorgente.La maschera deve avere esattamente le stesse dimensioni dell'immagine sorgente, quindi generala dallo stesso file (strumento poligono, output di segmentazione) anziché ridimensionare uno screenshot.
• Fissa il seed durante la messa a punto.Usa lo stesso seed e modifica solo steps o guidance, così ogni differenza deriva da quel parametro.

Il costo per immagine è indicato nella pagina dei prezzi; controllalo prima di eseguire grandi volumi di materiale.

Cosa ha mostrato una vera esecuzione

Ho eseguito la richiesta curl sopra una volta sulla foto della stanza di esempio inclusa in questa pagina (1600×900) e sulla sua maschera rettangolare (riquadro bianco a x 840–1240, y 160–580). Impostazioni: steps: 30, guidance: 60, seed: 42, output_format: png.

• Tempo.L'attività è rimasta in handling per circa 25 secondi, poi in archiving, raggiungendo success in circa 38 secondi end-to-end.
• Dimensioni dell'output diverse dalla sorgente.Il PNG restituito era 1440×810, non 1600×900. Il rapporto d'aspetto è lo stesso, ma le dimensioni in pixel sono diverse. Se devi ricomporre il risultato sull'immagine originale, ridimensiona prima una delle due, non dare per scontato che siano 1:1.
• Invariato fuori dalla maschera.Dopo aver ridimensionato la sorgente a 1440×810 e averla confrontata con l'output, l'81% dei pixel all'interno del riquadro bianco variava di oltre 8 livelli (0–255), mentre solo lo 0,03% dei pixel fuori dal riquadro lo faceva. A oltre 12 px dal bordo della maschera, la differenza massima era di 11 livelli. Divano, cuscini, pianta, pavimento e luce della finestra non sono stati ridisegnati.
• Ambito del prompt.Il prompt descriveva solo il dipinto e ciò che andava mantenuto; il risultato è stata una scena lacustre montana incorniciata che riempiva il riquadro bianco.
• Un URL errato fallisce durante il polling, non alla creazione.Un'altra richiesta con image e mask impostati su stringhe non-URL ha restituito 200 e un taskId, poi l'attività è terminata dopo circa 3 secondi con status: fail e error.code: TASK_FAILED. Il successo del tuo POST non significa che gli input siano validi, quindi controlla sempre lo stato finale.

Non testato:maschere con dimensioni diverse dalla sorgente, maschere con valori grigi (bordi morbidi), maschere con canale alpha e valori estremi di guidance o steps. La documentazione afferma che la maschera deve corrispondere alle dimensioni della sorgente, e ho testato solo un rettangolo binario netto. Non ho eseguito più seed, quindi non posso dire quanto il riempimento vari tra esecuzioni.

Quando scegliere Fill Pro

Usalo quando la modifica deve fermarsi a un confine netto che controlli tu, ad esempio etichette di prodotto, linee delle pareti o cuciture dei vestiti. Per modifiche descritte a parole e senza maschera, usa un modello basato solo sul prompt. La guida all'inpainting delle immagini e alla rimozione di oggetti li confronta. Per cancellare qualcosa da una maschera senza scrivere un prompt, consulta la guida a Bria Eraser.

Correlati

• Pagina del modello FLUX.1 Fill Pro
• Riferimento API di flux-1-fill-pro
• Prezzi
• Come usare l'API Bria Eraser
• Guida a FLUX.2 image-to-image

Domande frequenti

image e mask sono entrambi obbligatori?

Sì. La documentazione attuale elenca image, mask e prompt come obbligatori.

Quale colore ridisegna il modello?

Il bianco. I pixel neri mantengono l'immagine sorgente.

La maschera deve avere le stesse dimensioni della sorgente?

La documentazione dice di sì. Nella mia esecuzione ho usato una coppia corrispondente e non ho testato casi non corrispondenti.

Come sono le dimensioni dell'output?

Nella mia esecuzione, una sorgente da 1600×900 ha restituito un PNG da 1440×810, con lo stesso rapporto d'aspetto.