Tutoriale
Come chiamare flux-2/text-to-image tramite l'API HiAPI: tutorial con curl e Python
Guida pratica a una richiesta funzionante: identificatore di modello, parametri prompt e aspect ratio, campi della risposta e gestione degli errori
In questa pagina
Cosa espone flux-2/text-to-image tramite l'API
Prima di scrivere la prima riga di codice, è utile capire con precisione a cosa ti stai collegando. Su HiAPI, flux-2/text-to-image non è un SDK separato da installare, né un servizio a sé con autenticazione propria. È un identificatore di modello che, insieme al prompt che descrive l'immagine desiderata, viene inviato all'endpoint condiviso di generazione immagini.
Questo modello mentale è importante perché delimita i confini dell'integrazione. Il tuo codice ha bisogno di tre cose:
- Le credenziali di autenticazione per l'API HiAPI.
- L'endpoint che accetta le richieste di generazione immagini.
- Un payload JSON contenente
model(impostato suflux-2/text-to-image) eprompt.
Tutto il resto — aspect ratio, preferenze di output e qualsiasi altro parametro esposto dal modello — risiede nel payload come campo aggiuntivo. Ecco perché passare a flux-2/text-to-image da un altro modello text-to-image richiede di solito una sola modifica di configurazione, non una riscrittura del codice: l'involucro della richiesta resta identico, cambia solo il valore di model.
L'endpoint riceve la richiesta, la esegue attraverso il modello e restituisce una risposta strutturata contenente l'immagine generata (di solito un URL o un payload codificato) e i metadati del job. Per una chiamata di base non serve interrogare una coda di job separata — dal punto di vista del client il ciclo richiesta/risposta è sincrono, ma la generazione sottostante richiede comunque tempo, quindi il timeout del tuo client HTTP dovrebbe essere impostato in modo generoso.
Tieni a mente questo quadro: un endpoint, un payload, una stringa di modello. Il resto del tutorial completa il payload e rende solida la chiamata.
Costruire una richiesta funzionante con curl
Il modo più rapido per verificare che credenziali e struttura del payload siano corrette è una chiamata curl. Ottieni una risposta di successo nel terminale prima di passare a Python — questo isola i problemi di autenticazione e payload dai bug a livello di linguaggio.
Per prima cosa imposta la chiave come variabile d'ambiente, così non resta in chiaro nella cronologia della shell:
export HIAPI_API_KEY="your_api_key_here"
Poi invia la richiesta:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/text-to-image",
"prompt": "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
"aspect_ratio": "16:9"
}'
Punti da verificare quando la esegui:
- Endpoint e chiave provengono dalla dashboard del tuo account HiAPI. Copiare l'endpoint dalla dashboard invece di ridigitarlo evita il fallimento silenzioso più comune — richieste inviate a un indirizzo inatteso.
-sSmantiene l'output pulito ma mostra comunque gli errori a livello di curl, come fallimenti DNS o TLS.- L'header
Authorizationusa lo schema bearer standard. Nessuno spazio finale né virgolette attorno all'espansione della variabile. Content-Type: application/jsonè obbligatorio; senza di esso il corpo della richiesta può essere rifiutato prima che il modello lo veda.
Se la chiamata va a buon fine, vedrai nel terminale il corpo JSON della risposta. Passalo a un formattatore per migliorarne la leggibilità:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"flux-2/text-to-image","prompt":"a red fox in fresh snow, eye level","aspect_ratio":"1:1"}' \
| python3 -m json.tool
Una volta che funziona, hai una base di riferimento certa. Qualsiasi errore successivo in Python può essere confrontato con questa chiamata che hai confermato valida.
I parametri prompt e aspect ratio
Due campi della richiesta influenzano di più l'output: prompt e aspect_ratio. Modifica un solo parametro alla volta, altrimenti non potrai capire quale dei due ha causato il cambiamento che osservi.
Il prompt
Il prompt è la descrizione in linguaggio naturale dell'immagine. Scrivilo come una descrizione compatta della scena, non come una lista di parole chiave — più o meno nell'ordine soggetto, ambiente, illuminazione e composizione. Confronta:
- Vago:
a lighthouse - Specifico:
a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot
Durante gli esperimenti mantieni la formulazione esplicita e stabile. Se riscrivi il prompt e cambi l'aspect ratio nello stesso ciclo di iterazione, hai due variabili e una sola osservazione. Congela il prompt, modifica una parola alla volta e annota il cambiamento effettivo.
Abitudini utili:
- Metti il soggetto più importante all'inizio della stringa.
- Descrivi illuminazione e atmosfera con parole concrete, non astratte.
- Conserva nel codice un piccolo set di prompt di riferimento e rieseguili ogni volta che cambi altro, così puoi distinguere un cambiamento di comportamento del modello da un cambiamento del prompt.
L'aspect ratio
aspect_ratio controlla la forma dell'output — orizzontale per paesaggi e banner, quadrata per avatar e miniature, verticale per poster e layout mobile. Il modello accetta stringhe di proporzione come 16:9, 1:1 o gli equivalenti verticali; usa le proporzioni documentate per il modello, non inventarne di arbitrarie.
Poiché l'aspect ratio è un singolo campo discreto, è il parametro più facile da esplorare. Scrivi un ciclo che mantiene fisso il prompt e richiede la stessa immagine in tre proporzioni, poi confronta le composizioni affiancate. Capirai presto quali proporzioni tagliano il soggetto e quali gli lasciano spazio.
Un'avvertenza: l'aspect ratio cambia la composizione effettiva, non solo la tela. Un prompt scritto per un'inquadratura ampia può risultare debole in una cornice quadrata. Una volta fissata la proporzione, rivedi il prompt una volta per compensare.
Trasferire la chiamata in Python
La chiamata curl si converte direttamente in Python. L'obiettivo è una piccola funzione che riceve prompt e aspect ratio, legge la chiave dall'ambiente e restituisce il JSON analizzato — in forma pronta per la produzione, non come script usa e getta.
import os
import requests
IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"
def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # fail fast if unset
payload = {
"model": MODEL,
"prompt": prompt,
"aspect_ratio": aspect_ratio,
}
response = requests.post(
IMAGE_ENDPOINT,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
Note sul perché è scritto così:
- Variabili d'ambiente, non valori letterali.
os.environ[...]solleva subito unKeyErrorse la variabile manca, molto meglio che inviare un bearer token vuoto e poi decodificare un errore di autenticazione confuso più tardi. json=payloadfa serializzare il corpo della richiesta arequestse imposta ilContent-Typeper te. Non costruire manualmente la stringa JSON.- Timeout esplicito. La generazione di immagini non è istantanea; il timeout predefinito del client ti creerà problemi sotto carico. Impostalo deliberatamente.
raise_for_status()converte le risposte non 2xx in eccezioni catturabili e classificabili, invece di restituire silenziosamente un corpo di errore che sembra un dato.
Per chiamarla:
result = generate_image(
"a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
aspect_ratio="16:9",
)
print(result)
Se preferisci httpx, la forma è identica — cambia l'import e mantieni gli stessi header, il payload con json= e il parametro timeout. Ciò che conta è il payload, che resta invariato rispetto alla versione curl.
Leggere la risposta
Una chiamata riuscita restituisce un oggetto JSON. Invece di indovinare i nomi dei campi, ispeziona prima una risposta reale e scrivi il parser in base a ciò che vedi davvero. Esegui la tua funzione e stampa le chiavi di primo livello:
result = generate_image("a red fox in fresh snow, eye level", "1:1")
print(result.keys())
I campi che userai di solito si dividono in due gruppi:
- L'immagine stessa. La risposta contiene l'immagine generata — di solito un URL che puoi scaricare o servire, talvolta dati immagine codificati. Leggi il nome esatto del campo dalla tua risposta, salva quel valore e gestiscilo in base alla sua forma. Se è un URL, trattalo come a breve scadenza: scaricalo o copialo nel tuo storage tempestivamente, invece di salvarlo in un database e dare per scontato che sia ancora risolvibile il mese prossimo.
- I metadati. Aspettati campi di contorno che descrivono la generazione — il modello usato, l'aspect ratio o le dimensioni richieste e un identificatore della richiesta. Registrali insieme all'immagine. Quando un utente segnala che un'immagine "non sembra giusta", i metadati ti dicono quale prompt e quale proporzione l'hanno prodotta, senza doverli ricostruire dallo stato dell'applicazione.
Un pattern di estrazione sicuro:
image_ref = result.get("image") or result.get("data")
if not image_ref:
raise ValueError(f"no image in response; keys={list(result.keys())}")
È volutamente difensivo. I nomi dei campi sono stabili nel modello, ma scrivere l'accessor in modo che fallisca rumorosamente con la lista effettiva di chiavi evita che un None silenzioso si propaghi nella tua UI. Dopo aver confermato i nomi dei campi da una risposta reale, puoi rendere il codice più stringente e leggerli direttamente.
Infine, non scartare la risposta grezza. Conservala (o registrala nei log per le richieste parziali) finché l'integrazione non si stabilizza — quando qualcosa va storto a valle, è la fonte di verità.
Errori comuni e come risolverli
La maggior parte dei fallimenti alla prima esecuzione rientra in poche categorie. Gestiscili per classe di stato HTTP, non confrontando il testo dei messaggi, che cambia senza preavviso.
Errori di autenticazione (401 / 403)
Chiave mancante, malformata o priva dei permessi necessari. Controlla in ordine: HIAPI_API_KEY è effettivamente impostata nell'ambiente visibile al tuo processo; l'header è esattamente Authorization: Bearer <key>, senza spazi superflui o virgolette di troppo; non hai inviato per errore una chiave proveniente da un altro ambiente. Se curl funziona ma Python no, stampa gli header che invii e confrontali carattere per carattere.
Payload malformato (400)
Il corpo della richiesta viene rifiutato prima della generazione. Cause comuni: JSON non valido (stringhe costruite a mano con virgole finali), prompt mancante o Content-Type errato. La soluzione è usare json=payload in Python e -d con JSON valido in curl. Registra nei log il payload che stai per inviare e leggilo come farebbe una persona.
Parametri non supportati o non validi (400 / 422)
Nomi di campo o valori che il modello non accetta — un aspect_ratio scritto male, una proporzione non documentata per il modello o un campo extra copiato dall'esempio di un altro modello. Riduci il payload al minimo (model, prompt), poi aggiungi i campi uno alla volta per individuare il problema.
Limite di frequenza (429)
Stai inviando richieste più velocemente di quanto consenta il limite del tuo account. È temporaneo. Non riprovare in un ciclo serrato — usa un backoff con ritardo crescente e un tetto al numero di tentativi. Se lavori in batch, aggiungi piccole pause tra le chiamate invece di inviarle tutte insieme.
Errori lato server (5xx) e timeout
Sono temporanei e fuori dal tuo controllo. Riprova con backoff e assicurati che il timeout sia abbastanza lungo da non classificare come errore una generazione lenta. Un timeout di lettura scattato mentre il modello sta ancora lavorando genera un nuovo tentativo e spreca una richiesta.
Tenere la classificazione in un unico posto la rende manutenibile:
def classify(status: int) -> str:
if status in (401, 403):
return "auth" # fix config, do not retry
if status in (400, 422):
return "payload" # fix request, do not retry
if status == 429:
return "rate_limit" # retry with backoff
if status >= 500:
return "server" # retry with backoff
return "other"
Incapsulare la chiamata per la produzione
La funzione di sopra funziona, ma un'integrazione reale ha bisogno di tre cose che le mancano: retry che distinguano i fallimenti temporanei da quelli permanenti, timeout che riflettano la realtà e log che ti permettano di ricostruire cosa è successo. Un piccolo wrapper copre tutte e tre.
import logging
import time
log = logging.getLogger(__name__)
def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
delay = 1.0
for attempt in range(1, attempts + 1):
try:
return generate_image(prompt, aspect_ratio)
except requests.HTTPError as exc:
status = exc.response.status_code
kind = classify(status)
log.warning("flux-2 call failed", extra={
"attempt": attempt, "status": status,
"kind": kind, "aspect_ratio": aspect_ratio,
})
if kind in ("auth", "payload"):
raise # retrying will not help
if attempt == attempts:
raise
time.sleep(delay)
delay *= 2
Perché ogni parte è preziosa:
- Riprova solo ciò che è ritentabile. Gli errori di autenticazione e di payload sono deterministici — ritentarli spreca tempo e maschera bug reali. I limiti di frequenza, gli errori server e i timeout ottengono il backoff esponenziale.
- Registra campi strutturati, non prosa. Numero del tentativo, stato, categoria di errore e parametri usati ti permettono di raggruppare i fallimenti in seguito. Non registrare mai le chiavi API.
- Limita i tentativi. Un ciclo di retry illimitato trasforma un singolo guasto in un processo bloccato.
- Mantieni i timeout espliciti e generosi. Passali dalla configurazione, così puoi aumentarli nei periodi di lentezza nota senza modificare il codice.
Altre due abitudini che ripagano: conservare per ogni immagine generata un hash di (model, prompt, aspect_ratio), così puoi riprodurre qualsiasi output; e mantenere nella suite di test un piccolo set di prompt di riferimento da eseguire dopo ogni modifica al wrapper. Insieme, trasformano lo snippet del tutorial in qualcosa di gestibile operativamente.
Con la forma della richiesta definita e la gestione degli errori a posto, cambiare modello in futuro richiederà solo una modifica di una riga al campo model — che è esattamente lo scopo di chiamare flux-2/text-to-image tramite un'interfaccia unificata.
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