Blog

Tutoriale

Come chiamare flux-1-fill-pro tramite l'API HiAPI: curl, Python e polling asincrono

Nov 12, 2026
Immagine di copertina del blog HiAPI: su uno sfondo blu indaco scuro, tre frecce larghe annidate avanzano progressivamente in direzione orizzontale, con il bordo anteriore in arancione albicocca, in uno stile piatto da diagramma di flusso di segnali.
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.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API