Blog

Tutoriale

Come chiamare fibo-2.0/text-to-image tramite l'API HiAPI: pratica con curl e Python

Nov 13, 2026
Immagine di copertina: piani traslucidi in vetro sovrapposti su uno sfondo grigio-azzurro chiaro, che rifrangono una sobria fascia di colore blu, componendo una struttura geometrica astratta.
In questa pagina

Cosa costruirai in questo tutorial

Questa è una guida pratica che ti porta a ottenere davvero un'immagine da fibo-2.0/text-to-image su HiAPI. Alla fine avrai due cose eseguibili subito: un comando curl che genera una richiesta di generazione immagine valida e una piccola funzione Python che fa lo stesso e restituisce il risultato per ulteriori elaborazioni.

Procederemo nell'ordine in cui la maggior parte degli sviluppatori lavora davvero. Prima verifichiamo che ambiente e credenziali siano pronti. Poi leggiamo campo per campo il corpo della richiesta, così hai chiaro cosa controlla ogni parte. Quindi inviamo la chiamata con curl per dimostrare che endpoint, chiave e payload sono coerenti. Solo dopo portiamo la stessa richiesta in Python, dove inizia il lavoro davvero interessante: analizzare la risposta, gestire i fallimenti e incapsulare tutto in una funzione.

L'obiettivo non è elencare tutti i parametri possibili, ma darti una forma di richiesta che comprendi appieno, così potrai adattare prompt, dimensioni di output e codice circostante ai tuoi casi d'uso senza tirare a indovinare.

Prima di inviare la prima richiesta

Prima che la prima chiamata riesca, devono sussistere tre condizioni.

Account HiAPI e chiave API

Le richieste a fibo-2.0/text-to-image richiedono autenticazione. Genera una chiave API nel tuo account HiAPI e tienila lontana dal controllo di versione. Gli esempi seguenti leggono la chiave da una variabile d'ambiente invece di codificarla a mano: fallo fin dal primo giorno, perché aggiungere la gestione della chiave in seguito è noioso.

export HIAPI_API_KEY="your-api-key-here"

Uno strumento in grado di inviare richieste HTTP

Per la parte pratica con curl ti serve curl sulla tua macchina. È fornito con macOS e con la maggior parte delle distribuzioni Linux; su Windows è disponibile nelle versioni recenti e in Windows Terminal. Per la parte Python ti servono Python 3 e la libreria requests, il modo più comune di effettuare chiamate HTTP da uno script. Se non l'hai ancora installata:

pip install requests

Sapere cosa vuoi generare

Prepara un prompt. I modelli di immagini reagiscono con forza a descrizioni concrete ed esplicite — soggetto, stile, illuminazione e composizione — quindi una sola riga di idea di solito basta per iniziare a testare. Dopo il primo risultato continuerai a raffinarlo; è un ciclo normale.

Con queste tre cose a posto, tutto il resto riguarda il corpo della richiesta.

Analisi del corpo della richiesta campo per campo

La chiamata a fibo-2.0/text-to-image è una richiesta POST con corpo JSON. Il corpo è piccolo: un prompt e le impostazioni che modellano l'output. Invece di memorizzare l'intero payload, comprendi ogni campo, così potrai modificarlo con cognizione di causa.

Identificatore del modello

Il percorso dell'endpoint stesso indica il modello: fibo-2.0/text-to-image. Nella maggior parte dei casi non serve passare una stringa di modello aggiuntiva — la rotta che chiami determina quale modello viene eseguito. Se la tua integrazione supporta l'instradamento tramite un endpoint condiviso, metti il nome del modello in una costante di configurazione, così potrai cambiarlo senza toccare il punto di chiamata.

Il prompt

Questo è l'input centrale: la descrizione testuale dell'immagine che vuoi. Trattalo come una specifica, non come un desiderio. Indicare soggetto, stile visivo e composizione dà al modello più informazioni utilizzabili rispetto a concetti astratti. Metti il prompt in una variabile o in un file separato, così potrai iterare rapidamente senza riscrivere il codice della richiesta.

Impostazioni di output

Le richieste di immagini di solito portano un piccolo insieme di controlli di output — i più comuni sono le dimensioni o le proporzioni dell'immagine generata, e il numero di risultati se ne vuoi più di uno. Usa i nomi di campo documentati per fibo-2.0/text-to-image nel riferimento dei modelli HiAPI; il payload di esempio qui sotto usa questi nomi canonici. Se un'impostazione non è documentata per quel modello, omettila anziché indovinare — i campi sconosciuti sono una fonte comune di errori di validazione.

Cosa non mettere nel corpo della richiesta

Non inserire la chiave API nel corpo JSON. L'autenticazione appartiene agli header. Tenere le credenziali fuori dal payload significa che il corpo può essere registrato e confrontato in sicurezza durante il debug — cosa che apprezzerai quando la prima richiesta fallirà.

Una richiesta curl funzionante

Ecco una chiamata completa. Sostituisci il tuo prompt ed eseguila in una shell in cui è impostata HIAPI_API_KEY.

curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "un porto tranquillo all'alba, una leggera nebbia si posa sull'acqua, composizione ampia, stile fotografico",
    "size": "1024x1024",
    "n": 1
  }'

Il ruolo di ogni parte

  • -X POST imposta il metodo HTTP. La generazione di immagini è un'operazione di creazione, quindi è POST, non GET.
  • L'URL punta alla rotta fibo-2.0/text-to-image sull'host dell'API HiAPI. Se il tuo account usa un URL di base regionale o specifico del progetto, sostituisci quell'host e mantieni il percorso.
  • Authorization: Bearer $HIAPI_API_KEY passa la tua chiave dall'ambiente. La shell espande la variabile, quindi la chiave non appare mai come stringa letterale nella cronologia dei comandi.
  • Content-Type: application/json dice al server che il corpo è JSON. Senza di esso, molti gateway lo rifiutano prima ancora che la richiesta raggiunga il modello.
  • -d '...' è il corpo JSON: prompt, dimensioni richieste e numero di immagini.

Verifica del risultato

Esegui il comando e guarda prima l'output grezzo. Una chiamata riuscita restituisce un documento JSON che descrive l'immagine generata; una chiamata fallita restituisce un oggetto di errore. Prima di costruire qualsiasi cosa sopra, assicurati di riuscire a distinguere ad occhio le due cose. Se la risposta è grande, elaborala con uno strumento di formattazione come jq per rendere la struttura leggibile:

curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"un porto tranquillo all'alba","size":"1024x1024","n":1}' | jq .

Una volta che la chiamata manuale funziona, hai scagionato credenziali e payload. Ogni problema successivo è nel tuo codice.

La stessa chiamata in Python

La versione Python fa esattamente ciò che fa il comando shell, ma ti offre un posto dove validare l'input, riprovare e salvare i risultati. Mantienila piccola ed esplicita.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"

def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    payload = {
        "prompt": prompt,
        "size": size,
        "n": n,
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate_image(
        "un porto tranquillo all'alba, una leggera nebbia si posa sull'acqua, composizione ampia, stile fotografico"
    )
    print(result)

Perché è scritto così

  • La chiave viene letta dall'ambiente all'interno della funzione, quindi se manca la chiamata fallisce rumorosamente all'avvio anziché inviare una richiesta non autenticata.
  • json=payload fa sì che requests serializzi il corpo e imposti correttamente il content type. Non costruire stringhe JSON a mano in Python; introducono errori di virgolette che scopri solo a runtime.
  • timeout=60 rende espliciti i fallimenti lenti. La generazione di immagini non è istantanea, quindi scegli un timeout che sei disposto ad attendere, ma impostane sempre uno.
  • raise_for_status() trasforma le risposte 4xx e 5xx in eccezioni. È proprio questa riga a impedire che una chiamata fallita venga gestita silenziosamente come riuscita.
  • La funzione accetta prompt, size e n come parametri, così il resto del programma può chiamarla come qualsiasi altra funzione di libreria.

Esegui il file e dovresti vedere la stessa struttura JSON restituita dalla chiamata curl.

Leggere la risposta e gestire gli errori

Una risposta riuscita ti fornisce un oggetto JSON che descrive l'output generato. Il dettaglio che ti interessa è l'immagine generata stessa — di solito un URL o un riferimento che puoi scaricare o memorizzare — insieme a qualsiasi metadato sulla richiesta restituito dall'API. Analizza la risposta come dati; non estrarla con manipolazioni di stringhe. Se la forma non corrisponde alle aspettative alla prima ispezione della risposta reale, controlla prima il riferimento del modello e solo dopo modifica il parser, perché indovinare i nomi dei campi è proprio il modo in cui l'integrazione si rompe silenziosamente.

Rilevare i fallimenti

Ci sono tre livelli di fallimento da gestire intenzionalmente.

Errori di trasporto. La richiesta non è mai stata completata: errore DNS, connessione reimpostata, timeout. In Python si manifestano come requests.exceptions, e sono sicuri da ritentare con backoff.

Stati HTTP di errore. Il server ha risposto ma ha rifiutato la richiesta. 401 di solito significa chiave mancante o errata; gli errori di validazione 4xx di solito significano nomi o valori di campo errati; 429 significa che stai inviando troppo velocemente; 5xx significa che c'è un problema lato server. raise_for_status() li cattura tutti come un'unica eccezione, quindi prima di decidere cosa fare controlla il messaggio nel corpo della risposta.

Codice di stato 200 ma corpo inatteso. Ecco perché devi validare la struttura invece di darla per scontata. Verifica che i campi su cui fai affidamento esistano prima di usarli e, anche con stato 200, tratta un riferimento all'immagine mancante come un fallimento.

try:
    result = generate_image("un porto tranquillo all'alba")
    image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
    print("richiesta fallita:", exc.response.status_code, exc.response.text)

Abitudine importante: non ingoiare mai silenziosamente gli errori. Registra almeno il codice di stato e il corpo della risposta, perché questa coppia di informazioni ti dice se correggere il payload oppure attendere e riprovare.

Verso la produzione

Una volta che la singola chiamata funziona e i fallimenti sono visibili, qualche piccola abitudine rende l'integrazione solida sotto traffico reale.

Riprovare solo ciò che è sicuro ritentare

Gli errori di trasporto, i timeout, le risposte 429 e 5xx meritano un nuovo tentativo con backoff esponenziale e un limite di tentativi. Gli errori di validazione e 401 no — ripetere una richiesta malformata consuma solo quota. Distingui esplicitamente le due categorie nella gestione degli errori.

Tenere la configurazione fuori dal codice

Metti l'URL di base dell'API, il percorso del modello, le dimensioni predefinite e il timeout nella configurazione, anziché sparpagliarli nelle funzioni. Quando passerai dall'ambiente di test a un ambiente diverso, o proverai in seguito un modello simile, dovrai cambiare un solo punto.

Registrare richieste e risposte, ma togliere le chiavi

Registra i prompt, i parametri, i codici di stato e le risposte troncate. Non registrare mai la chiave API. Così potrai rispondere una settimana dopo alla domanda "perché questa immagine è tornata sbagliata" senza dover riprodurre il caso.

Validare l'input prima di inviarlo

Controlla che il prompt non sia vuoto e rientri in una lunghezza ragionevole, e che size e n corrispondano ai valori documentati del modello. Catturare valori errati in locale è più veloce e più economico di un round trip.

Salvare i risultati, non solo stamparli

Il riferimento all'immagine generata può essere temporaneo. Scarica o copia l'output nel tuo storage come parte dello stesso job, e registra quale prompt e quali parametri l'hanno prodotto. Quel record rende possibile rigenerare e verificare.

Incapsulando fibo-2.0/text-to-image nella piccola funzione generate_image di questo tutorial, fai dipendere il resto della tua applicazione da quella funzione anziché dalla chiamata HTTP grezza. Quando sarai pronto a variare i prompt su larga scala, il riferimento dei modelli HiAPI è il posto dove confermare i parametri supportati prima di estendere l'interfaccia.

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