Tutoriale

Come si usa l'API FLUX.1 Fill Pro? La prima inpainting con maschera in 5 minuti

I quattro requisiti rigorosi della maschera, 4 passaggi per la prova online, 4 passaggi per l'integrazione API, con curl e Python pronti all'uso.

Oct 28, 2026

TL;DR

Cos'è: il modello di inpainting localizzato con maschera di Black Forest Labs. Carichi l'immagine originale, una maschera in bianco e nero delle stesse dimensioni e un prompt, e ridisegna solo l'area bianca mantenendo intatta quella nera. È già disponibile su HiAPI, apri la pagina del modello per provarlo, i nuovi utenti ricevono 200 crediti alla registrazione.
Quanto costa: $0.0715 per immagine (143 crediti), addebitati solo per le generazioni riuscite, steps, guidance, seed e formato di output non hanno sovrapprezzo, in caso di fallimento l'importo prenotato viene rimborsato. Con $10 ottieni circa 139 immagini.
Come chiamarlo al volo: POST https://api.hiapi.ai/v1/tasks, in model scrivi flux-1-fill-pro, in input inserisci i tre campi image, mask e prompt, dopo aver ottenuto il taskId fai polling o attendi il callback, quindi scarica data.output[0].url.

L'ostacolo più frequente nell'inpainting con maschera non sono i parametri, ma i materiali: la maschera deve avere le stesse dimensioni dell'immagine originale e il bianco deve coprire solo le zone da modificare. Di seguito chiariamo prima questi due aspetti, poi passiamo alla prima esecuzione.

Cos'è FLUX.1 Fill Pro?

È un modello di editing che «modifica solo la parte che selezioni». L'area di intervento è determinata dalla maschera, non dal testo, quindi i mobili, le ombre e la linea dell'orizzonte circostanti non cambiano.

La maschera copre solo la piccola porzione di parete con l'orologio, output 1440 × 810. L'arazzo a sinistra, i piatti intrecciati, il teschio di bisonte, le piante, il divano e l'illuminazione non sono stati ridisegnati.

Tre input. Immagine originale (JPEG / PNG / GIF / WebP), maschera in bianco e nero delle stesse dimensioni, prompt (massimo 4.000 caratteri).
Confini controllabili. Il bianco viene ridisegnato, il nero conservato, le modifiche si fermano ai bordi della maschera, ideale per ritocchi di prodotto, sostituzione di sfondi, cambio colore di abiti e altri lavori in cui «si tocca solo un punto».
L'output segue l'immagine originale. Non ci sono parametri di proporzioni, il rapporto viene ripreso dall'originale; un'immagine 1600 × 900 restituisce 1440 × 810, con dimensioni arrotondate ai multipli di 32.
Parametri sufficienti e semplici. steps 15–50 con default 50, guidance 1.5–100 con default 60, seed opzionale e output jpg / png.

A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.

Genera con questo prompt → il link precompila solo il prompt: lo slot dell'immagine originale è vuoto, lo slot della maschera contiene la maschera di esempio per impostazione predefinita. Sostituiscili con la tua immagine originale e una maschera delle stesse dimensioni, poi premi Esegui.

Come preparare la maschera?

Quattro punti chiave, da seguire in questo ordine:

Solo due valori, bianco e nero. Il bianco è l'area da ridisegnare, il nero quella da conservare. I bordi grigi rendono i confini sfumati, cerca di ottenere bordi netti.
Dimensioni identiche all'immagine originale. Un'immagine 1600 × 900 richiede una maschera 1600 × 900. Non fare screenshot e poi ridimensionare, esporta la maschera direttamente dallo stesso file; se larghezza e altezza non corrispondono il task fallisce.
L'area bianca aderisce all'obiettivo. Fermati quando hai coperto ciò che vuoi modificare, non includere mobili, piani di lavoro o ombre adiacenti.
Esporta la maschera in PNG alla risoluzione dell'originale. Il PNG non introduce rumore da compressione, i bordi restano più puliti; carica maschera e immagine originale su indirizzi accessibili pubblicamente, l'API riceve URL, non file caricati.

Il nero conserva, il bianco ridisegna. Questa maschera 1600 × 900 ha un solo rettangolo bianco in corrispondenza dell'orologio, quindi solo quella porzione di parete verrà ridisegnata.

Prova online: 4 passaggi per la prima immagine

La pagina del modello non permette di disegnare la maschera: va preparata nel tuo strumento preferito e poi caricata.

Apri la pagina del modello FLUX.1 Fill Pro, registrati o accedi, i nuovi account hanno 200 crediti inclusi.
Carica l'immagine originale, poi la maschera in bianco e nero delle stesse dimensioni.
Incolla il prompt, descrivendo solo il contenuto che deve apparire nell'area bianca e specificando cosa va conservato.
Premi Esegui. I default sono steps 50, guidance 60, output jpg: prima verifica che funzioni, poi regola i parametri.

Quando apri la pagina con «Genera con questo prompt», il prompt viene compilato automaticamente. Lo slot dell'immagine è vuoto, quello della maschera contiene la maschera di esempio: sostituiscila con la tua prima di eseguire.

Integrazione API: 4 passaggi

Crea una API Key nella dashboard (sk-...).
POST /v1/tasks per creare il task, con image, mask e prompt in input.
Interroga con GET /v1/tasks/{taskId}, oppure aggiungi callback.url nella richiesta e attendi la notifica.
Quando data.status diventa success, scarica l'immagine da data.output[0].url e salvala subito nel tuo storage.

La tabella completa dei campi, i codici di errore e la descrizione dei parametri sono nella documentazione in cinese.

Prima inpainting con maschera: versione curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-fill-pro",
    "input": {
      "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
      "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
      "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
      "steps": 50,
      "guidance": 60,
      "output_format": "png"
    }
  }'

L'ID del task restituito si trova in data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Per interrogare il risultato:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Le due immagini qui sopra sono materiali di confronto 1:1: l'originale 1600 × 900 e la maschera delle stesse dimensioni, eseguile direttamente per ottenere l'effetto del dipinto mostrato nella prima immagine dell'articolo.

Prima inpainting con maschera: versione Python

Creazione, polling e download in un unico script, basta sostituire la tua Key per eseguirlo:

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "flux-1-fill-pro",
    "input": {
        "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
        "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
        "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
        "steps": 50,
        "guidance": 60,
        "output_format": "png",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    status = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if status["status"] in ("success", "fail"):
        break
    time.sleep(3)

if status["status"] == "success":
    image_url = status["output"][0]["url"]
    with open("fill-pro-edit.png", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(status.get("error"))

Come regolare i parametri?

Cambia un solo parametro alla volta, così capisci subito quale ha prodotto la differenza.

steps (15–50, default 50): valori più alti danno più dettaglio, il default è già adatto alla resa finale, abbassalo solo quando hai fretta.
guidance (1.5–100, default 60): valori più alti seguono più fedelmente il prompt. Se lo stile devia, aumentalo; se l'immagine risulta rigida, riducilo.
seed: dopo aver scelto il risultato definitivo, fissa un valore per tornare a risultati simili con stessa immagine, stessa maschera e stesso prompt, utile per rollback e uniformità in batch.
output_format: default jpg; per conservare il massimo dettaglio o per ulteriori elaborazioni, usa png.
prompt_upsampling: default false. Attivandolo il prompt viene riscritto automaticamente; se vuoi controllare completamente la formulazione, lascialo disattivato.

4 cose da sapere prima del lancio in produzione

Non si può disegnare la maschera nella pagina. Sia la pagina del modello che l'API accettano solo maschere già pronte, che devono avere le stesse dimensioni dell'immagine originale. Prepara la maschera in Photoshop, Figma o con strumenti di segmentazione; nella pagina è possibile solo caricarla, non disegnarla.
Sul server usa i callback. Aggiungi al corpo della richiesta "callback": {"url": "https://yourapp.com/webhook", "when": "final"} per ricevere una notifica automatica al termine del task, più comodo del polling; mantieni comunque il polling come fallback.
In caso di timeout non ripetere il POST. Ogni POST /v1/tasks crea un nuovo task e viene addebitato separatamente. Salva prima il taskId e, in caso di retry, riutilizza lo stesso task per interrogare.
Gli URL di output scadono. Scarica e salva subito il file appena ottieni il risultato, non trattare l'URL come indirizzo permanente; inoltre il rapporto di output segue l'immagine originale e non ci sono parametri di formato, per mantenere un formato fisso ritaglia tu in base al rapporto.

Domande frequenti

Si può usare senza maschera? No. image, mask e prompt sono tutti obbligatori, e la maschera deve essere un'immagine in bianco e nero delle stesse dimensioni dell'originale.

Quanto deve essere lungo il prompt? Massimo 4.000 caratteri, ma basta il necessario: una frase per ciò che deve apparire nell'area bianca, una per ciò che va conservato. Descrizioni più specifiche danno risultati più stabili.

Le dimensioni di output sono uguali all'originale? Il rapporto è identico, i pixel vengono arrotondati ai multipli di 32. Un'immagine 1600 × 900 restituisce 1440 × 810: per sovrapporla all'originale, uniforma prima le dimensioni.

Se la generazione fallisce vengono addebitati costi? No. L'importo prenotato per i task falliti viene rimborsato automaticamente per intero.

Genera ora la tua prima immagine

I due materiali di confronto qui sopra (immagine originale + maschera) sono pronti per esercitarti: copia il corpo della richiesta curl e sostituisci la tua API Key per eseguirlo, oppure apri la pagina del modello e carica queste due immagini con il prompt già compilato: premendo Esegui ottieni lo stesso risultato. Questa immagine costa $0.0715, i 200 crediti regalati alla registrazione bastano per una generazione.

Articoli della serie FLUX.1 Fill Pro

Tagintegrazione-api Esercitazione Integrazione API Esercitazione