Tutoriale
Come usare Nano-Banana tramite l'API HiAPI: curl, Python e richieste eseguibili
In questa pagina
Cosa offre Nano-Banana come API agli sviluppatori
Nano-Banana è un modello di generazione di immagini reso disponibile tramite l'API HiAPI. Inviate un prompt — e, se necessario, una o più immagini di riferimento — e ricevete l'immagine generata. Il modello mentale complessivo è davvero così semplice. Nessun modello da ospitare localmente, nessuna GPU da preparare, nessun SDK aggiuntivo da imparare: l'autenticazione, l'incapsulamento delle richieste e il meccanismo dei task asincroni che usate con gli altri modelli HiAPI valgono anche qui.
Prima di scrivere codice è utile chiarire cosa è e cosa non è l'endpoint di generazione di immagini. È un endpoint creativo: lo stesso prompt può produrre risultati diversi in esecuzioni diverse, e la vostra pipeline dovrebbe essere progettata per tollerarlo. Non è una trasformazione deterministica come un ridimensionamento o una conversione di formato. Se avete bisogno di riproducibilità a livello di pixel, memorizzate in cache gli output che avete approvato, invece di presumere che una rigenerazione dia lo stesso risultato.
Un'integrazione tipica si articola in tre fasi:
- Inviare una richiesta di generazione con il prompt e gli eventuali input opzionali.
- Attendere il completamento del task generato, perché la generazione di immagini richiede più tempo di un semplice completamento testuale.
- Recuperare l'output, memorizzarlo e decidere se accettarlo oppure modificare il prompt e riprovare.
Ci sono due cose da decidere fin dall'inizio, perché influenzano tutto il resto: se il vostro prompt è solo testo o usa immagini di riferimento (questo cambia il payload della richiesta), e se avete bisogno di coerenza del personaggio tra più generazioni (che quasi sempre implica l'uso di immagini di riferimento). Le sezioni seguenti si sviluppano dalla struttura della richiesta verso l'esterno; potete adattare gli esempi man mano.
Anatomia di una richiesta Nano-Banana
Ogni richiesta a Nano-Banana tramite HiAPI ha lo stesso scheletro. Cambia solo il payload.
Endpoint e autenticazione
Le richieste vanno all'URL di base di HiAPI, e il modello specifico si indica nel payload della richiesta, non in un URL upstream costruito a mano. L'autenticazione avviene tramite l'header Authorization con la vostra API key. Conservate la chiave in una variabile d'ambiente — mai inline nel codice sorgente o committata nel repository.
Nome del modello
L'identificatore del modello è un campo nel vostro corpo JSON. Trattatelo come una stringa da copiare alla lettera dalla lista dei modelli, non come qualcosa da comporre a mano, così i cambi di denominazione non romperanno silenziosamente il vostro codice.
Payload del prompt
Dovete inviare almeno un prompt testuale che descriva l'immagine desiderata. Qui la qualità del prompt influisce sull'output molto più di qualsiasi altro campo. Siate specifici su soggetto, composizione, illuminazione e stile. Prompt vaghi producono immagini vaghe, e nessuna impostazione dei parametri può salvare un prompt che non esprime ciò che volete davvero.
Immagini di riferimento opzionali
Se includete immagini di riferimento, fanno parte dello stesso corpo della richiesta — di solito fornite come URL di immagine o dati immagine codificati, a seconda del formato accettato dal modello. Le immagini di riferimento possono ancorare elementi come il volto di un personaggio, l'abbigliamento o lo stile artistico complessivo. Omettele per la generazione solo testo; includetele quando l'output deve somigliare a un soggetto specifico.
Campi relativi all'output
Alcuni campi influenzano la forma del risultato più che il contenuto: ad esempio la dimensione di output o le proporzioni richieste. È meglio considerarli valori richiesti, non garantiti — le dimensioni restituite dal modello possono variare leggermente. Il codice a valle dovrebbe leggere le dimensioni effettivamente restituite, non presumere che ciò che avete richiesto sia ciò che otterrete.
Ecco la struttura concettuale, con valori segnaposto:
{
"model": "<nano-banana-model-id>",
"prompt": "Una volpe rossa seduta nell'erba alta durante l'ora d'oro, profondità di campo ridotta",
"reference_images": [],
"size": "1024x1024"
}
Consultate la documentazione dei parametri del modello per i nomi esatti dei campi e i formati accettati — la struttura sopra è solo uno schema generico e non sostituisce la documentazione di riferimento.
Richiesta curl eseguibile
Il modo più rapido per verificare che la chiave funzioni e che il payload sia valido è eseguire una chiamata curl. Impostate prima l'ambiente:
export HIAPI_API_KEY="your-api-key-here"
Poi inviate la richiesta di generazione:
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<nano-banana-model-id>",
"prompt": "Una volpe rossa seduta nell'erba alta durante l'ora d'oro, profondità di campo ridotta",
"size": "1024x1024"
}'
A cosa serve ogni parte:
- URL — il percorso di generazione immagini di HiAPI. Un unico URL di base serve tutti i modelli; il modello si specifica nel corpo della richiesta.
Authorization— la vostra chiave, letta dall'ambiente, così non finisce nella cronologia della shell o nel controllo di versione.Content-Type— deve essereapplication/json; un errore comune dei principianti è dimenticarlo e ottenere errori di parsing.- Corpo della richiesta — il payload JSON della sezione precedente, con dentro il prompt che volete davvero.
Interpretare la risposta
La risposta vi dice cosa è successo. Due esiti meritano attenzione:
- Risultato sincrono — alcune chiamate restituiscono direttamente i dati dell'immagine o un URL dell'immagine. Se vedete un URL, scaricatelo e memorizzatelo al più presto, senza contare sulla sua disponibilità a lungo termine.
- Handle del task — se la generazione è asincrona, la risposta contiene un identificatore da usare per il polling dello stato. È l'argomento della sezione asincrona qui sotto.
Se volete vedere insieme al corpo della risposta anche la riga di stato HTTP e gli header, aggiungete -i al comando curl — è molto utile in caso di errore per distinguere un problema di autenticazione da un problema di payload.
La stessa chiamata in Python
A parte gli script una tantum, usate Python. La libreria requests mantiene leggere le dipendenze degli esempi e rende esplicito e visibile il livello HTTP.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
payload = {
"model": "<nano-banana-model-id>",
"prompt": "Una volpe rossa seduta nell'erba alta durante l'ora d'oro, profondità di campo ridotta",
"size": "1024x1024",
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Alcune buone abitudini da adottare fin da subito:
- Impostate un timeout. La generazione di immagini è lenta; senza timeout il vostro worker potrebbe bloccarsi indefinitamente. Per le chiamate sincrone un timeout generoso è un buon punto di partenza, ma regolatelo in base al vostro carico.
- Usate
raise_for_status(). Converte le risposte 4xx e 5xx in eccezioni catturabili, invece di interpretare silenziosamente un corpo di errore come risultato. - Incapsulate in una funzione. Lo snippet sopra è uno script; in un servizio vi servirà una funzione che riceva un prompt e restituisca i dati dell'immagine o l'handle del task, così il resto del codice non deve preoccuparsi dei dettagli HTTP.
Se la risposta contiene un URL dell'immagine, scaricatela e memorizzatela subito:
for item in data.get("data", []):
url = item.get("url")
if url:
img = requests.get(url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
La vera fonte di dati della vostra applicazione dovrebbe essere il vostro storage — non URL remoti temporanei.
Gestire i task asincroni
La generazione di immagini richiede di solito più tempo di quanto una singola richiesta HTTP dovrebbe mantenere la connessione aperta. I modelli HiAPI che funzionano così restituiscono un identificatore di task al momento dell'invio, e poi fate polling dell'endpoint di stato del task finché il lavoro non è completato. Lo schema vale per tutti i modelli asincroni della piattaforma, quindi basta impararlo una volta.
Prima inviate, poi fate polling
La vostra POST iniziale restituisce qualcosa di simile a un ID di task. Poi fate polling dell'endpoint di stato con quell'ID. La logica che vi serve è:
import time
def poll_task(task_id, api_key, interval=2, max_wait=300):
headers = {"Authorization": f"Bearer {api_key}"}
deadline = time.time() + max_wait
while time.time() < deadline:
r = requests.get(
f"https://api.hiapi.ai/v1/tasks/{task_id}",
headers=headers,
timeout=30,
)
r.raise_for_status()
body = r.json()
status = body.get("status")
if status in ("succeeded", "completed", "failed", "error"):
return body
time.sleep(interval)
raise TimeoutError(f"Il task {task_id} non è stato completato entro {max_wait} secondi")
Tre regole che vi risparmiano problemi
- Limitate sempre il tempo di attesa totale. Un task che non finisce mai non deve bloccare il vostro worker. Il
max_waitqui sopra è la vostra via d'uscita. - Fate backoff. Un intervallo fisso breve va bene per l'uso interattivo; per i lavori batch aumentate l'intervallo man mano che l'attesa cresce, per non martellare l'endpoint di stato.
- Verificate lo stato finale.
succeededsignifica che potete leggere l'output;failedsignifica che dovete leggere il payload di errore invece di riprovare alla cieca. Riprovare un payload malformato fa solo perdere tempo.
Persistete l'ID del task insieme ai vostri record dei lavori. Se il processo si riavvia a metà del polling, potete riprendere il polling invece di reinviare e pagare per una generazione duplicata.
Immagini di riferimento e coerenza del personaggio
I prompt solo testuali vanno bene per immagini una tantum, ma quando vi serve lo stesso personaggio in dieci scene diverse non bastano. Descrivere un volto a parole e sperare che il modello lo riproduca in modo stabile quasi non funziona — piccole variazioni di formulazione generano persone diverse.
Le immagini di riferimento risolvono il problema. Includete nella richiesta una o più immagini insieme al prompt testuale, e il modello le usa come ancore visive. La coerenza del personaggio è il caso d'uso centrale:
- Scheda del personaggio — un'immagine di riferimento pulita, più prompt per più scene, mantenendo coerenti volto e abbigliamento.
- Ancoraggio dello stile — l'immagine di riferimento fissa il linguaggio visivo, il prompt guida il contenuto.
- Immagini di prodotto — l'immagine di riferimento dell'oggetto mantiene stabile il suo design su sfondi diversi.
Nella richiesta questo significa popolare il campo delle immagini di riferimento invece di inviarlo vuoto. Fornite le immagini come URL o dati codificati, a seconda di ciò che supporta la specifica dei parametri del modello, e mantenete pulite le immagini di riferimento: un soggetto chiaro batte una scena caotica, perché il modello coglie tutto ciò che c'è nell'inquadratura, non solo la parte che vi interessa.
Un pattern pratico per la pipeline:
- Generate un personaggio una volta da un prompt testuale dettagliato.
- Rivedetelo, accettatelo o rigeneratelo finché non siete soddisfatti.
- Usate quell'immagine approvata come immagine di riferimento per ogni scena successiva.
È il flusso di lavoro nano banana API python in sintesi: fissate il personaggio una volta, poi cambiate solo la parte della scena nel prompt. Aspettatevi iterazioni — le immagini di riferimento migliorano la coerenza ma non raggiungono la perfezione, quindi costruite una fase di revisione invece di dare per scontato che ogni output sia utilizzabile.
Risoluzione di output e limiti reali
La risoluzione è il punto in cui è più facile sbagliare per assunzioni, quindi trattatela con cautela.
Dimensione richiesta e dimensione effettiva
Potete richiedere una dimensione di output, ma dovete considerarla un suggerimento. Le dimensioni restituite dal modello possono differire da quelle richieste — soprattutto per proporzioni poco comuni. L'approccio robusto è leggere le dimensioni effettive dell'immagine ricevuta e gestirle in modo generico: storage, miniature e layout dovrebbero basarsi sul file reale, non sui valori richiesti.
Da cosa dipende la qualità
La qualità dell'output dipende soprattutto dal prompt e, quando usate, dalle immagini di riferimento. Un prompt ben composto, con soggetto e illuminazione chiari, produce immagini migliori di un prompt vago che chiede solo una dimensione maggiore. Non usate la risoluzione per compensare un prompt poco descrittivo.
Progettate intorno ai limiti
- Non codificate le dimensioni nel codice a valle. Leggetele dall'immagine restituita.
- Verificate prima di memorizzare. Se la vostra applicazione richiede una dimensione minima, controllate le dimensioni effettive dopo la generazione; se insufficienti, rigenerate — non date per scontato che la richiesta abbia imposto quel requisito.
- Attenzione alla dimensione dei file. Output a risoluzione più alta significano payload più grandi; scaricate in streaming o con buffer, invece di caricare tutto in memoria in un ciclo.
- Fate batch con prudenza. I limiti di concorrenza sono per account; se dovete generare molte immagini, aggiungete un piccolo pool di worker con retry e backoff, invece di scatenare richieste in un ciclo senza limiti.
Per conoscere le capacità autorevoli e i valori accettati di Nano-Banana, fate riferimento alla documentazione del modello — non ai payload di esempio di questo articolo. La fatturazione segue il normale modello a consumo della piattaforma; per le tariffe attuali consultate il pannello dei prezzi, non questo tutorial.
Diagnosticare gli errori comuni
La maggior parte dei fallimenti alla prima integrazione rientra in poche categorie. Ecco cosa controllare per ciascuna.
401 / 403 — autenticazione
La vostra chiave manca, è malformata o non viene inviata. Verificate che l'header Authorization sia presente, con il prefisso Bearer , e che la variabile d'ambiente sia effettivamente esportata nella shell o nel processo che esegue il codice. I caratteri di newline finali in più quando si copia una chiave causano questo problema più spesso di quanto ci si aspetti.
400 — payload malformato
Di solito è uno dei seguenti: JSON non valido (virgolette in eccesso o virgole finali), Content-Type errato, campi obbligatori mancanti (come prompt o model), oppure il campo delle immagini di riferimento inviato in un formato che il modello non accetta. Stampate l'esatto corpo della richiesta che state inviando e confrontatelo campo per campo con la specifica dei parametri.
404 — percorso o modello errato
Il percorso dell'endpoint è sbagliato, oppure l'identificatore del modello non corrisponde a nessun modello della piattaforma. Copiate il nome del modello così com'è dalla lista, invece di digitarlo a memoria.
Timeout e polling bloccato
Per le chiamate sincrone, un timeout troppo breve interrompe lavori che sarebbero andati a buon fine. Per i lavori asincroni, un polling bloccato di solito significa che la logica di polling esce troppo presto, oppure che il controllo dello stato finale non corrisponde alle stringhe di stato effettivamente restituite dall'API — registrate i valori di stato originali e verificate. Mantenete sempre un tempo di attesa massimo, così i lavori bloccati falliscono in modo evidente invece di restare appesi.
Risultato vuoto
Un 200 senza immagini è quasi sempre un problema di contenuto, non un bug: il prompt potrebbe essere troppo vago, oppure essere stato filtrato. Prima di concludere che l'API è guasta, controllate i campi di errore o di motivo nel corpo della risposta, poi rendete il prompt più preciso e chiaro.
Fallimenti al retry
Se lo stesso payload a volte riesce e a volte fallisce, probabilmente avete colpito un limite di frequenza o un errore transitorio del server. Aggiungete backoff esponenziale intorno all'invio e al polling, e non riprovate un 400 — correggete il payload.
In caso di dubbio, la diagnosi più rapida è una chiamata curl minima con un prompt semplice. Se funziona, il problema è nel vostro payload o nel codice, non nelle credenziali.
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