Tutoriale
Come usare flux-3 tramite l'API HiAPI: curl, Python ed esempi di richiesta eseguibili
In questa pagina
Cosa ottieni usando flux-3 tramite HiAPI
flux-3 è un modello di generazione di immagini che gestisce sia il text-to-image sia l'image-to-image. Se stai costruendo funzionalità di prodotto, strumenti di design o pipeline interne, la parte davvero interessante spesso non è il modello in sé, ma quanto pulitamente riesci a collocarlo dietro un'interfaccia stabile e prevedibile, mantenendo questa condizione quando i requisiti cambiano.
È qui che sta il valore di una piattaforma API aggregatrice. Chiamare flux-3 tramite HiAPI significa che tu:
- Integri una sola volta. Un'unica URL di base, un unico metodo di autenticazione e una struttura di richiesta e risposta coerente tra i modelli che usi. Cambiare o confrontare modelli diventa poi una questione di configurazione, non di riscrittura del codice.
- Elimini il lavoro infrastrutturale. Nessun modello da ospitare, nessuna capacità GPU da pianificare, nessun cold start da gestire dalla tua parte. Invii una richiesta HTTP e gestisci la risposta.
- Centralizzi le credenziali. Una sola API key da emettere, ruotare e limitare nei permessi, invece di dover instaurare rapporti separati con ogni provider upstream.
- Ottieni una semantica degli errori uniforme. Indipendentemente dal modello dietro la chiamata, i codici di stato e l'involucro degli errori sono gli stessi, il che rende riutilizzabili la logica di retry e di allerta.
Applicato a flux-3, questo significa che puoi passare direttamente da un prototipo in notebook a un endpoint di produzione senza cambiare la struttura del codice client. Le due modalità di generazione — text-to-image e image-to-image — condividono la stessa struttura di richiesta, quindi supportarle entrambe dipende da quali campi popoli, non da quale SDK importi.
In tutto l'articolo si usano le seguenti convenzioni:
- URL di base: l'endpoint dell'API HiAPI indicato nella console del tuo account.
- Autenticazione: bearer token nell'header
Authorization. - Content type:
application/jsonper il corpo della richiesta; le immagini di input vengono fornite come URL o come dati codificati in base64, a seconda dei limiti di dimensione del payload.
Tieni le chiavi nelle variabili d'ambiente — non committerle mai nel controllo del codice sorgente. Gli esempi seguenti leggono la chiave da HIAPI_API_KEY e l'identificatore del modello da FLUX_MODEL, così puoi adattarli senza modificare il codice.
Fatte queste premesse, la sezione successiva scompone il corpo della richiesta stesso.
Anatomia di una richiesta: text-to-image e image-to-image
Una chiamata a flux-3 si divide logicamente in tre parti: il percorso dell'endpoint, gli header di autenticazione e un corpo JSON. Il corpo della richiesta è dove le due modalità divergono, e comprenderne la differenza ti permette di riutilizzare un unico client per entrambe.
Struttura condivisa
Ogni richiesta contiene campi in una delle seguenti forme:
- model — il modello da chiamare; qui il tuo identificatore flux-3.
- input — l'oggetto che contiene le istruzioni di generazione.
- input.prompt — descrizione in linguaggio naturale di ciò che vuoi. Obbligatorio in entrambe le modalità.
- Impostazioni di generazione opzionali — come dimensioni di output, rapporto d'aspetto o numero di passi, a seconda di ciò che il modello espone. Imposta solo ciò che ti serve; i valori predefiniti sono di solito già ragionevoli.
- Controllo asincrono opzionale — flag o callback che cambiano il modo in cui il job viene eseguito e consegnato (dettagliati nella prossima sezione).
Text-to-image
In modalità text-to-image, prompt è l'unico campo sostanziale. Descrivi l'immagine, eventualmente vincoli la geometria di output, poi invii. Non c'è un'immagine sorgente, quindi il modello ha il massimo grado di libertà — il che significa anche che la qualità del prompt determina la qualità dell'output.
Una buona abitudine: scrivi il prompt come faresti con un illustratore umano. Segui l'ordine di soggetto, composizione, illuminazione, stile e qualsiasi vincolo rigido (ad esempio "nessun testo nell'immagine", "soggetto centrato"). I prompt vaghi producono risultati mediocri, indipendentemente dal numero di passi.
Image-to-image
In modalità image-to-image, aggiungi al prompt un campo per l'immagine sorgente; il prompt descrive ora la trasformazione rispetto a quell'input, non una scena costruita da zero. A seconda dell'interfaccia del modello, questo può significare fornire un URL dell'immagine o un payload codificato, più eventuali parametri di forza o guida che controllano quanto l'output si discosta dalla sorgente.
Per il tuo client API, l'impatto pratico è minimo: stesso endpoint, stessa autenticazione, stesso oggetto input — solo un campo in più. Questo è esattamente l'obiettivo di progettazione. La tua funzione generate() dovrebbe accettare un'immagine sorgente opzionale e gestire internamente la diramazione, così il chiamante non deve mai sapere quale modalità ha attivato.
Struttura della risposta
La risposta dovrebbe contenere un identificatore del job e, al completamento, la posizione dell'immagine generata. Tratta quella posizione come un valore opaco: puoi recuperarla o memorizzarla, ma non fare supposizioni sul suo contenuto. Alcune risposte tornano immediatamente, altre sono handle di job — ed è proprio per questo che la gestione asincrona va prevista nel design fin dal primo giorno.
Parametri e modalità asincrona
Scegliere le impostazioni di generazione
Le impostazioni di generazione sono un compromesso tra qualità, latenza e costo. Questi principi valgono per la maggior parte dei modelli di immagine, incluso flux-3:
- Risoluzione e rapporto d'aspetto influenzano sia l'utilità dell'output sia il consumo di calcolo. Genera alla dimensione che consegni effettivamente; ridurre un'immagine grande spreca budget, ingrandire una piccola spreca rendering.
- Passi o controllo qualità migliorano la fedeltà fino a un certo punto, poi si appiattiscono. Trova empiricamente questo punto di flesso con un prompt fisso e fermati lì.
- Controllo della determinismo (se disponibile) è importante per la riproducibilità. Se devi rigenerare lo stesso risultato per QA o supporto utente, registra le impostazioni insieme all'output.
Non indovinare i nomi dei parametri o gli intervalli accettabili: leggi la documentazione del modello nella console e prendila come riferimento. Se un campo viene rifiutato, la risposta di errore ti dice esattamente quale.
Sincrono vs. asincrono
La generazione di immagini non è un'operazione istantanea. Esistono due modalità di esecuzione:
Sincrona (bloccante). Invii la richiesta e mantieni la connessione aperta finché l'immagine non è pronta. È semplice e adatta a job brevi, script e strumenti interattivi in cui l'utente guarda un'animazione di caricamento. Ma è anche fragile: funzioni serverless, load balancer e client mobili hanno limiti di timeout, e un rendering lungo finirà inevitabilmente per colpirne uno.
Asincrona (basata su job). Invii la richiesta, ricevi subito un identificatore, poi esegui il polling di un endpoint di stato o ricevi una callback finché il job non segnala il completamento. Scegli questa modalità quando:
- hai runtime serverless o edge con limiti rigidi di durata di esecuzione.
- hai job batch che devono inviare in parallelo molti rendering.
- vuoi qualsiasi flusso di interazione utente che restituisca subito il controllo e faccia avanzare lo stato in streaming.
Progetta il client intorno all'asincrono, poi avvolgi i casi semplici in un metodo di comodo sincrono. Fare il contrario — forzare l'asincrono dentro un client bloccante — raramente porta a buoni risultati.
Durante il polling, usa un backoff esponenziale con limite invece di un ciclo stretto fisso, imposta un tetto al tempo di attesa totale e considera i job che non raggiungono mai uno stato finale come errori degni di allerta.
Una richiesta curl eseguibile
Inizia dal terminale; una volta che lo scambio HTTP grezzo è chiaro, le versioni in codice sono semplici.
1. Configura l'ambiente
export HIAPI_API_KEY="your-key-here"
export FLUX_MODEL="your-flux-3-model-id"
export HIAPI_BASE="https://your-hiapi-endpoint"
Metti l'identificatore del modello in una variabile — cambiare modello in futuro richiederà una sola riga.
2. Invia una richiesta text-to-image
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "A minimal studio photograph of a ceramic mug on a concrete surface, soft side light, shallow depth of field"
}
}'
Il flag -sS mantiene l'output pulito mostrando comunque gli errori. Prima di eseguire, verifica il percorso esatto rispetto all'endpoint documentato nella console — i percorsi sono versionati e la documentazione è la fonte di verità.
3. Leggi il contenuto restituito
Passa la risposta attraverso uno strumento di formattazione per renderla leggibile:
... | python -m json.tool
Concentrati su due cose: l'identificatore del job e la posizione dell'immagine o il campo di stato che ti dice che il job è ancora in esecuzione. Se vedi uno stato invece dell'immagine, sei sul percorso asincrono — annota l'identificatore e passa al polling.
4. Prova l'image-to-image
Aggiungi l'immagine sorgente all'oggetto input, lasciando il resto invariato:
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "Reinterpret as a watercolor painting, keep the composition and shadows intact",
"image": "https://example.com/source.jpg"
}
}'
Poiché la richiesta differisce per un solo campo, la tua prima chiamata riuscita ha già validato la maggior parte dell'integrazione. Il resto — retry, archiviazione, UI — è normale lavoro applicativo.
La stessa richiesta in Python
La chiamata curl si traduce direttamente. Quella che segue è un client piccolo e riutilizzabile, non uno script monouso.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE"]
MODEL = os.environ["FLUX_MODEL"]
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def generate(prompt, image=None, timeout=60):
"""Submit a flux-3 generation job. Pass image= for image-to-image."""
payload = {"model": MODEL, "input": {"prompt": prompt}}
if image:
payload["input"]["image"] = image
resp = requests.post(
f"{BASE}/v1/images/generations",
headers=HEADERS,
json=payload,
timeout=timeout,
)
resp.raise_for_status()
return resp.json()
Alcune scelte intenzionali:
- Una funzione, due modalità. Il parametro
imagecambia il comportamento, senza diramazioni per il chiamante. - Timeout esplicito. Il comportamento predefinito di
requests— attendere all'infinito — è esattamente il modo in cui si esaurisce un pool di thread di lavoro. raise_for_status(). Fa emergere i fallimenti del livello HTTP come eccezioni, che puoi intercettare in un unico punto.
Aggiungere un helper di polling
Quando la risposta contiene un identificatore di job invece dell'immagine completata, attendi:
def wait_for(job_id, timeout=300, initial=1.0, factor=1.6, cap=15.0):
deadline = time.monotonic() + timeout
delay = initial
while time.monotonic() < deadline:
r = requests.get(
f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30
)
r.raise_for_status()
data = r.json()
if data.get("status") in ("succeeded", "failed"):
return data
time.sleep(delay)
delay = min(delay * factor, cap)
raise TimeoutError(f"job {job_id} did not finish in {timeout}s")
Adatta il nome del campo di stato alla struttura della risposta documentata. La struttura in sé — backoff con limite, scadenza rigida, controllo dello stato finale — è la parte essenziale e si applica invariata quando cambi modello.
Mettere tutto insieme
if __name__ == "__main__":
result = generate(
"A minimal studio photograph of a ceramic mug, soft side light"
)
if "id" in result and not result.get("output"):
result = wait_for(result["id"])
print(result)
Successivamente, avvolgi generate nel tuo livello di retry e logging, e l'integrazione sarà pronta per la produzione.
Controllo dei costi ed errori comuni
Mantenere la spesa prevedibile
La generazione di immagini viene addebitata per richiesta, con un importo che dipende dal modello e dalle impostazioni — consulta il pannello dei prezzi in tempo reale nella console invece di codificare ipotesi. La disciplina ingegneristica è ciò che protegge il budget:
- Imposta limiti per utente e per job nel tuo codice. La piattaforma applica limiti a livello di account; la tua applicazione dovrebbe applicare limiti a livello di prodotto, così un singolo client fuori controllo non esaurisce l'account.
- Fai caching in modo aggressivo. Calcola un hash del prompt normalizzato insieme alle impostazioni e riutilizza gli output memorizzati. Le richieste identiche sono comuni negli scenari di editor e anteprima.
- Genera alla risoluzione di consegna. Renderizza alla dimensione che mostrerai; evita il costoso schema "renderizza grande e poi riduci".
- Subordina la rigenerazione a un'azione esplicita dell'utente. La rigenerazione automatica a ogni tasto premuto nella casella del prompt è il moltiplicatore di costi accidentali più comune.
- Registra modello, impostazioni e latenza di ogni chiamata. Senza questi dati, non puoi capire quale funzionalità costa di più.
- Valida l'input prima di inviare. Rifiuta lato client i prompt vuoti o anormalmente lunghi, così non pagherai mai per richieste destinate a fallire.
Fare debug degli errori che incontrerai davvero
Segui questa checklist in ordine; risolve la maggior parte degli incidenti.
- 401 / 403 — autenticazione. La chiave è caricata nell'ambiente in cui gira effettivamente la richiesta? Una chiave disponibile nella tua shell potrebbe non esistere nel container. Verifica che il prefisso
Bearere il nome dell'header siano esattamente corretti. - 404 — percorso o modello errato. I percorsi versionati e gli identificatori dei modelli cambiano. Confronta carattere per carattere con l'endpoint documentato.
- 422 / 400 — payload rifiutato. Il corpo dell'errore indica il campo problematico. Sospetti comuni: tipo errato,
promptmancante o parametro non supportato. Reinvia rimuovendo le impostazioni opzionali per isolare il problema. - 429 — rate limit raggiunto. Esegui backoff con jitter e riprova; non riprovare immediatamente in un ciclo. Distingui questo caso dall'esaurimento della quota a livello di account, per cui i retry non servono.
- Timeout. Se la richiesta impiega troppo, stai bloccando dove dovresti fare polling. Passa al flusso asincrono e imposta consapevolmente i timeout del client.
- Job bloccato in pending. Esegui polling con una scadenza e tratta il timeout come un fallimento che merita allerta, non come un'attesa infinita.
Un'abitudine tiene insieme tutta la lista: registra il corpo completo dell'errore, non solo il codice di stato. Il corpo dell'errore di solito ti dice esattamente quale campo o limite ha causato il problema, trasformando mezz'ora di debug in una correzione da una riga.
Fai funzionare prima la chiamata curl, portala nel client qui sopra, centralizza polling e gestione degli errori in un unico punto — il resto dell'integrazione è normale codice applicativo. Per le capacità e i prezzi attuali del modello, consulta la documentazione e il pannello dei prezzi di flux-3 nella console HiAPI.
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