Blog

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

Nov 12, 2026
Immagine di copertina: su uno sfondo blu indaco scuro, ampie frecce annidate una dentro l'altra avanzano in sequenza verso destra, con il bordo anteriore color albicocca, piatte e precise come un diagramma di flusso di segnali.
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 su flux-2/text-to-image) e prompt.

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.
  • -sS mantiene l'output pulito ma mostra comunque gli errori a livello di curl, come fallimenti DNS o TLS.
  • L'header Authorization usa 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 un KeyError se la variabile manca, molto meglio che inviare un bearer token vuoto e poi decodificare un errore di autenticazione confuso più tardi.
  • json=payload fa serializzare il corpo della richiesta a requests e imposta il Content-Type per 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.

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