Tutoriale
Come chiamare flux-1-fill-pro tramite l'API HiAPI: curl, Python e polling asincrono
In questa pagina
Cosa fa flux-1-fill-pro e quando usarlo
flux-1-fill-pro è un modello di editing di immagini di tipo fill. Gli fornisci un'immagine sorgente e una maschera che contrassegna le aree da rigenerare, e restituisce una nuova immagine in cui tali aree sono state sostituite. Le zone fuori dalla maschera dovrebbero rimanere invariate: è proprio questo a distinguerlo dai modelli di pura generazione testo-immagine o di stilizzazione dell'intera immagine.
Va usato quando l'editing è locale e il contesto circostante è importante:
- Rimozione di oggetti — cerchia con una maschera gli elementi indesiderati e lascia che il modello ricostruisca ciò che dovrebbe esserci dietro.
- Sostituzione di oggetti — delimita l'area con una maschera, descrivi il nuovo contenuto nel prompt e mantieni invariato il resto della scena.
- Ritocchi locali — correggi texture, riflessi o piccoli difetti senza rigenerare l'intera immagine.
- Inserimento in pipeline — ritocca a livello programmatico immagini di prodotti, miniature o asset generati, in cui solo un'area necessita di una seconda elaborazione.
Non è lo strumento adatto quando vuoi una composizione completamente nuova partendo da un prompt, oppure quando l'area della maschera è così grande che il modello sta di fatto generando l'immagine da zero: in quel caso l'endpoint di generazione standard si comporta in modo più prevedibile.
Il resto di questa guida spiega come integrare flux-1-fill-pro nel tuo codice tramite l'API HiAPI: struttura della richiesta, chiamata curl, equivalente in Python e la gestione dei task asincroni su cui la maggior parte delle prime integrazioni inciampa.
Preparazione e configurazione dell'autenticazione
Prima di inviare la prima richiesta, verifica tre cose.
Chiave API
Crea una chiave nel tuo account HiAPI e tienila lontana dal controllo di versione. Gli esempi seguenti la leggono da una variabile d'ambiente, così gli snippet si possono copiare in sicurezza:
export HIAPI_API_KEY="your_key_here"
In Python caricala allo stesso modo tramite os.environ. Se esegui in CI, iniettala come secret invece di commettere un file .env.
Identificatore del modello
Ogni richiesta specifica il modello per nome. In questa guida l'identificatore è flux-1-fill-pro. Mantienilo come costante nel codice invece di spargere stringhe letterali: così cambiare modello in futuro richiederà una sola modifica.
URL di base
Tutte le chiamate vanno all'URL di base dell'API HiAPI documentato nei riferimenti della piattaforma. Tienilo nella configurazione insieme alla chiave, così staging e produzione possono differire senza modifiche al codice.
Un promemoria strutturale prima di iniziare: le richieste di fill trasportano dati immagine. Invia le immagini codificate in base64 come JSON, invece di forzare un upload multipart; e mantieni un timeout client generoso, perché la codifica di immagini grandi aggiunge latenza prima ancora che la richiesta lasci il tuo processo. Consulta la documentazione della piattaforma per i limiti attuali sulla dimensione del payload; se la tua immagine sorgente supera il limite documentato, ridimensionala prima della codifica, invece di far fallire la richiesta al limite.
La struttura di una richiesta di inpainting
Indipendentemente dal linguaggio usato, ogni chiamata a flux-1-fill-pro ha la stessa composizione logica.
Immagine sorgente
L'immagine da modificare, codificata come stringa. Definisce la tela: le sue dimensioni determinano lo spazio di coordinate in cui vive la maschera, e il suo contenuto fornisce al modello il contesto che rende credibile il riempimento.
Maschera
La maschera contrassegna le aree che verranno rigenerate. È la fonte più comune di confusione, quindi esplicita quale convenzione usa il tuo payload: le aree contrassegnate dalla maschera sono quelle che il modello può modificare. Costruisci la maschera come immagine separata, rendendo visivamente distinte le aree da riempire e quelle da preservare. Invertire la maschera è il bug classico: otterrai un risultato in cui il modello ha modificato tutto tranne l'area che volevi.
La maschera deve avere esattamente le stesse dimensioni dell'immagine sorgente. Una maschera disegnata a una risoluzione diversa verrà rifiutata o silenziosamente disallineata, e in entrambi i casi sprecherai un round-trip.
Prompt
Una descrizione testuale di ciò che dovrebbe apparire all'interno della maschera. Sii specifico e locale: descrivi il contenuto e la sua relazione con l'ambiente circostante in termini di illuminazione o texture, non l'intera scena. "Una panchina di legno che prosegue il rivestimento della vetrina, con la luce morbida del pomeriggio proveniente da sinistra" offre al modello molte più indicazioni di "uno sfondo più bello".
Controlli opzionali
A seconda dell'insieme di parametri documentato, potresti anche poter passare un seed per la riproducibilità, oppure parametri di intensità che controllano quanto il riempimento può discostarsi dai pixel originali. Per i parametri che non esistono nella documentazione di riferimento attuale, trattali come non supportati invece di indovinarne i nomi.
Questi quattro elementi — modello, prompt, immagine sorgente, maschera — viaggiano tutti nello stesso corpo JSON. Le due sezioni successive inviano proprio questo corpo.
Una richiesta curl funzionante
Inizia con curl, così vedi l'envelope grezzo prima che qualsiasi libreria client lo mascheri.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json
Dove request.json è simile a questo:
{
"model": "flux-1-fill-pro",
"prompt": "Una panchina di legno che prosegue il rivestimento della vetrina, con la luce morbida del pomeriggio proveniente da sinistra",
"image": "<base64-encoded source image>",
"mask": "<base64-encoded mask image>"
}
Due trucchi pratici per costruire quel file. Primo, genera il payload base64 con dei comandi invece di incollarlo a mano:
base64 -w 0 source.png > source.b64
base64 -w 0 mask.png > mask.b64
Poi assemblali in request.json con un piccolo passaggio di jq o Python. Modificare manualmente blocchi base64 di diversi megabyte dentro un JSON è proprio la causa di payload troncati e di errori 400 confusi.
Interpretare la risposta
L'envelope della risposta ti dice qual è il passo successivo. I task completati restituiscono l'immagine modificata — di solito come URL o come campo base64, nel formato previsto dalla documentazione di riferimento attuale. I task messi in coda restituiscono un identificatore e uno stato che poi dovrai interrogare (vedi sotto). Non dare per scontato che la prima risposta contenga sempre i pixel; scrivi il parser in modo che gestisca entrambe le forme fin dal primo giorno, altrimenti dovrai riscriverlo la prima volta che i task si accodano sotto carico.
Controlla il codice di stato HTTP prima di analizzare il corpo della risposta. Un 4xx significa che la richiesta stessa è errata e riprovare non serve; correggi il payload.
La stessa chiamata in Python
La versione Python è la stessa richiesta, ma più comoda da usare. Nessun SDK necessario: requests verso l'endpoint HiAPI è sufficiente.
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()
Il timeout è intenzionale. Codificare e caricare immagini grandi richiede più tempo di una tipica chiamata JSON, e le richieste senza limite sono proprio la causa per cui gli script si bloccano silenziosamente nei batch job. Sollevare un'eccezione sui 4xx includendo il corpo della risposta trasforma fallimenti misteriosi in fallimenti leggibili.
Metti l'identificatore del modello e l'endpoint nella configurazione a livello di modulo, così un aggiornamento di versione richiede una sola modifica. Se elabori molte immagini, riutilizza una requests.Session in modo che le connessioni siano in pool invece di essere ricreate a ogni chiamata.
Il dizionario risultante è o un risultato completato oppure un handle di task: la sezione successiva tratta quest'ultimo caso.
Gestire i task asincroni e il polling
Le richieste di fill possono essere lente, quindi l'API potrebbe restituire un handle di task invece dell'immagine finita. Il pattern corretto è un ciclo di polling con limiti, non uno sleep fisso e una preghiera.
Il ciclo
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) # backoff graduale
current = fetch_job(current["id"])
raise TimeoutError(f"Job {job.get('id')} exceeded {timeout}s")
fetch_job usa lo stesso pattern di richiesta visto sopra, con l'id del task e le tue intestazioni di autenticazione, verso l'endpoint documentato per lo stato del task.
Perché usare il backoff invece di un intervallo fisso
Interrogare una coda in un ciclo serrato martella l'API senza alcun beneficio. Partire da un intervallo breve e raddoppiarlo progressivamente fino a un limite mantiene la reattività sui completamenti rapidi senza sprecare migliaia di polling su task lenti. Metti un tetto all'intervallo, così riesci comunque ad accorgerti del completamento in pochi secondi.
Perché timeout e fallimento sono cose diverse
Un timeout significa che sei tu ad aver smesso di attendere, non che il task sia fallito. Conserva l'id del task quando sollevi l'eccezione, così il chiamante può riprendere il polling più tardi senza reinviare e pagare due volte lo stesso lavoro. Nella tua pipeline tratta timeout, fallimento del task ed errori HTTP come tre eccezioni distinte: comprimerle in un unico errore generico rende la diagnosi degli incidenti in produzione molto più difficile.
Debug dei guasti comuni
La maggior parte delle risposte di errore rientra in poche categorie. Controllale in quest'ordine.
401 / 403 — Autenticazione
Prima verifica: l'intestazione è esattamente Authorization: Bearer <key>, senza virgolette e senza spazi bianchi residui da una variabile shell mai esportata? Un $HIAPI_API_KEY vuoto produce un token Bearer composto dalla sola parola Bearer, che fallisce allo stesso modo di una chiave errata.
400 — Payload malformato
Prima verifica: il corpo è ancora JSON valido dopo aver concatenato le stringhe base64? Esporta request.json e passalo a python -m json.tool. Un prefisso data:image/png;base64, nel campo immagine è una causa frequente: rimuovilo, a meno che la documentazione di riferimento non lo richieda esplicitamente.
Disallineamento maschera/immagine
Prima verifica: le dimensioni in pixel della maschera coincidono esattamente con quelle dell'immagine sorgente? Poi verifica la polarità: assicurati che l'area bianca sia quella in cui vuoi che il modello rigeneri. Un risultato che sembra l'opposto di ciò che hai chiesto è quasi sempre una maschera invertita, non un problema di prompt.
Prompt troppo ampio
Se le aree non mascherate cambiano, o se il riempimento sembra globale, la maschera è probabilmente troppo grande o il prompt copre troppo l'intera scena. Restringi entrambi: stringi la maschera all'area effettiva dell'edit e descrivi solo ciò che sta dentro la maschera.
Timeout del task
Prima verifica: la dimensione del payload. Un'immagine sorgente troppo grande è la causa più comune di task che non si completano mai. Ridimensionala, riprova una volta e, se il timeout persiste, confronta con i limiti di riferimento usando una piccola immagine di test prima di dare la colpa al servizio.
Campo risultato vuoto o mancante
Prima verifica: hai gestito la forma della risposta in coda? Un parser che legge solo la forma completata non vedrà nulla alla prima chiamata. Durante lo sviluppo registra l'intero envelope della risposta, così puoi vedere la forma prima di scrivere codice difensivo.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business