Tutoriale
Come chiamare fibo-2.0/text-to-image tramite l'API HiAPI: pratica con curl e Python
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 POSTimposta 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-imagesull'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_KEYpassa 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/jsondice 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=payloadfa sì cherequestsserializzi 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=60rende 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,sizeencome 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.
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