Blog

Tutoriale

Come chiamare fibo-gen-1.5/text-to-image tramite HiAPI: guida con curl e Python

Nov 12, 2026
Copertina con punti mezzatinta verde menta che formano un gradiente di densità silenzioso su un campo quasi nero.
In questa pagina

Costruire una richiesta funzionante con curl

fibo-gen-1.5/text-to-image è un modello testo-immagine gestito, accessibile tramite il pattern di richiesta standard di HiAPI. Questo dettaglio è più importante di quanto sembri a prima vista: non devi scaricare pesi, configurare GPU o imparare SDK specifici del modello. Basta inviare una richiesta HTTP con l'identificatore del modello e il prompt, e ricevi il risultato immagine. L'integrazione si concentra su tre punti: come progettare il prompt, quali parametri impostare e come gestire la risposta.

Prima di scrivere qualsiasi codice, ci sono alcune ipotesi che puoi adottare con sicurezza:

  • Autenticazione uniforme. Ogni chiamata a HiAPI include la tua chiave API nell'header della richiesta. Non esistono flussi di autenticazione specifici per modello.
  • Il modello si seleziona per nome. fibo-gen-1.5/text-to-image va inserito nel campo model del corpo della richiesta e deve essere scritto esattamente così, incluso il suffisso /text-to-image.
  • Dal punto di vista del chiamante, la generazione è sincrona. Invii la richiesta, attendi e ricevi l'output. Il budget di timeout deve riflettere la latenza reale di generazione, non presupporre una risposta immediata.
  • La risposta è strutturata. Ricevi un wrapper JSON, non un blocco binario grezzo, quindi devi prima analizzarlo per utilizzare l'immagine.

Se hai già integrato qualsiasi altro modello HiAPI, ti sembrerà familiare. Se questo è il tuo primo, il pattern che impari qui si trasferisce direttamente a tutto il resto della piattaforma. La conoscenza realmente specifica del modello riguarda la scelta dei parametri, che questa guida illustra più avanti.

Eseguire la stessa chiamata in Python

Inizia con la chiamata minima che funziona. Esporta la chiave, evitando che finisca in chiaro nella cronologia della shell:

export HIAPI_API_KEY="your_api_key_here"

Poi invia la richiesta:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fibo-gen-1.5/text-to-image",
    "prompt": "un pescatore segnato dal tempo che ripara una rete su un pontile di legno all'alba, luce coperta, fotografia 35mm",
    "size": "1024x1024",
    "n": 1
  }'

Tre punti meritano attenzione, perché sono i punti in cui i tentativi "copia-incolla e speriamo" di solito falliscono:

  1. La stringa del modello deve essere esatta. fibo-gen-1.5/text-to-image — non fibo-gen-1.5, né varianti di maiuscole/minuscole. Una minima deviazione restituisce un errore di modello non trovato, senza fallback silenzioso.
  2. La chiave va nell'header Authorization come bearer token. Non nel corpo della richiesta né nella query string.
  3. Content-Type: application/json è obbligatorio. Senza di esso, alcuni proxy e gateway corrompono il payload prima che raggiunga l'API.

Se vuoi vedere esattamente cosa viene restituito — inclusi gli header di risposta — aggiungi -i alla chiamata curl. Quando una risposta sembra vuota, è l'abitudine di debug più utile: ti dice se hai ricevuto un 200 con un corpo di forma anomala o uno stato non 2xx da gestire. In fase esplorativa, puoi canalizzare l'output in jq . per formattare il JSON.

Una volta che funziona, cambia il prompt e riesegui. Mantenere invariato il resto della chiamata isola le modifiche al prompt da quelle strutturali.

Passare alla produzione

Il passaggio da uno script funzionante a un'integrazione affidabile riguarda soprattutto le parti noiose. Checklist:

  • Le chiavi non entrano nel codice. Caricale da variabili d'ambiente o da un gestore di segreti, non committarle mai e ruotale con una cadenza che riesci davvero a rispettare. Usa chiavi diverse per sviluppo e produzione, così una fuga della chiave di sviluppo non compromette il traffico live.
  • Timeout espliciti e motivati. Imposta il limite in base alla latenza di generazione osservata nel tuo carico di lavoro, non a una stima. Registra la durata effettiva di ogni chiamata per giustificare quel numero.
  • Retry limitati e selettivi. Per guasti transitori — timeout, condizioni di rate limit — usa backoff esponenziale con un tetto massimo di tentativi. Non ritentare mai payload malformati o errori di autenticazione: falliranno allo stesso modo ogni volta, consumando la tua quota.
  • Verifica l'output prima di fidarti. Controlla che i byte decodificati raggiungano una dimensione ragionevole e che il file si apra come immagine valida. Un file vuoto o troncato che arriva alla CDN è peggio di un errore esplicito in fase di generazione.
  • Ogni generazione è tracciata. Memorizza prompt, parametri, risposta e timestamp insieme. Questo rende possibile in futuro la riproducibilità e l'attribuzione dei costi.
  • Le chiamate sono incapsulate dietro una funzione, non sparse ovunque. Un unico generate() significa che devi correggere la logica di retry, i timeout e il logging in un solo posto.

Inizia lanciando una richiesta pulita a fibo-gen-1.5/text-to-image con curl, poi porta in Python, quindi aggiungi il livello operativo attorno. La forma della richiesta resta sempre la stessa — cambiano solo le garanzie che costruisci attorno.

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