Tutoriale
Tutorial sull'API di Nano-Banana-2: usare curl e Python Requests funzionanti tramite hiapi
In questa pagina
Preparativi prima della prima chiamata
Prima di inviare qualsiasi richiesta a Nano-Banana-2, prepara quattro cose. Nessuna richiede molto tempo, e averle tutte pronte trasforma la prima richiesta in un esercizio di copia-incolla anziché in una caccia al tesoro.
1. Account hiapi e chiave API
Ogni richiesta viene autenticata tramite una chiave API associata al tuo account hiapi. Crea la chiave nella dashboard del tuo account e conservala in un luogo sicuro: un gestore di password o una variabile d'ambiente sulla tua macchina. Trattala come una password: non salvarla mai nel repository del codice e non incollarla in documenti condivisi.
Sulla tua macchina, esportala una volta per ogni sessione shell, così gli esempi seguenti potranno leggerla senza dover codificare nulla a mano:
export HIAPI_API_KEY="your_api_key_here"
2. URL di base dell'API
L'URL di base è l'indirizzo radice su cui si costruiscono tutte le richieste. Per costruire l'endpoint, aggiungi la rotta del modello in coda. Metti l'URL di base in una variabile di configurazione nel codice, anziché sparpagliarlo in più file: così, se cambia, dovrai modificare una sola riga.
3. Client per inviare le richieste
Per iniziare ti basta uno dei seguenti:
- curl: quasi certamente è già installato. Usalo per verificare che la chiave e il corpo della richiesta siano corretti prima di scrivere qualsiasi codice applicativo.
- Python 3 con la libreria
requests(pip install requests). La maggior parte dei lettori userà questo per costruire integrazioni reali.
Avere entrambi è utile: curl isola la richiesta dal tuo codice, così se qualcosa va storto puoi capire se il problema è nella chiamata API o nell'applicazione.
4. Sapere cosa vuoi generare
Nano-Banana-2 supporta sia text-to-image che image-to-image. Decidi in anticipo quale modalità ti serve, perché la struttura del corpo della richiesta è diversa (lo vedremo in dettaglio più avanti). Per la prima chiamata, inizia dal text-to-image: ha il minor numero di variabili.
Con la chiave esportata, il client installato e il prompt già pensato, è il momento di passare alla richiesta stessa.
Componenti di una richiesta a Nano-Banana-2
Una chiamata a Nano-Banana-2 è una richiesta POST con un corpo JSON. Ogni campo ha il suo ruolo: comprenderli separatamente significa poter modificare un solo elemento alla volta quando qualcosa va storto.
Endpoint
La richiesta viene inviata all'URL di base dell'API hiapi, con l'aggiunta della rotta del modello Nano-Banana-2. Il metodo è sempre POST, perché stai inviando un payload da elaborare, non recuperando una risorsa.
Header
Due header sono importanti:
Content-Type: application/json: indica all'API come interpretare il corpo della richiesta.Authorization: trasporta la tua chiave API. Gli esempi seguenti la leggono dalla variabile d'ambiente esportata in precedenza.
Se uno dei due header manca o è malformato, la richiesta fallisce prima ancora che il modello la veda. È la singola causa più comune di errori confusi.
Campi del corpo della richiesta
Una richiesta text-to-image contiene i seguenti campi:
model: specifica che il modello da eseguire è Nano-Banana-2. Scrivilo esplicitamente anche se esiste un valore predefinito; rende il codice autoesplicativo e ti protegge quando il valore predefinito cambia.prompt: descrive in linguaggio naturale l'immagine che desideri. È qui che avverrà la maggior parte del tuo lavoro di iterazione. Sii specifico: soggetto, composizione, stile, illuminazione. Un prompt vago produce risultati vaghi.- Input immagine: assente o vuoto per il text-to-image. Per l'image-to-image, contiene la tua immagine di riferimento (maggiori dettagli nella sezione dedicata).
- Parametri di output e dimensione: campi specifici del modello che influiscono sulla forma o sulle proporzioni del risultato restituito. Imposta solo i campi supportati dalla documentazione del modello; nelle API rigorose, i campi sconosciuti di solito significano richiesta rifiutata, non ignorata silenziosamente.
Cosa viene restituito
La risposta è in JSON. A seconda di come è costruita la chiamata, riceverai direttamente i dati dell'immagine generata o un riferimento a essa. Il tuo codice client deve prima controllare lo stato HTTP e poi esaminare il corpo della risposta: non dare per scontato che una risposta dall'aspetto di un 200 contenga un'immagine senza verificarlo.
La struttura è tutta qui: una richiesta POST autenticata con un piccolo corpo JSON esplicito. Il resto di questo tutorial è solo una variazione su questa forma.
Una richiesta curl funzionante
Questa è la chiamata completa minima che puoi inviare. Eseguila in un terminale in cui hai esportato la chiave API: in pochi secondi saprai se account, chiave e percorso di rete funzionano correttamente.
curl -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition"
}'
Imposta una volta l'URL di base nella shell, insieme alla chiave:
export HIAPI_BASE_URL="https://api.hiapi.ai"
(Usa l'URL di base mostrato nella tua dashboard hiapi: è il valore autorevole per il tuo account.)
Leggere l'output
curl stampa la risposta grezza su stdout. Se la chiamata ha successo, vedrai un JSON contenente l'immagine generata. Passalo a python -m json.tool per formattare l'output e confermare la struttura:
curl -s -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{"model":"nano-banana-2","prompt":"a red fox in fresh snow, side profile, crisp detail"}' \
| python -m json.tool
Interpretare ciò che vedi
- Risposta di successo: conferma che la chiave è valida, l'endpoint è corretto e il corpo della richiesta viene analizzato. Salva questo comando funzionante: è la tua base di riferimento.
- Risposta di errore: indica che c'è qualcosa di sbagliato nelle tre righe degli header o nel corpo della richiesta. Copia il testo dell'errore; la sezione di debug associa gli errori comuni alle relative soluzioni.
Il valore di partire da curl è l'isolamento. Chiave, header e JSON sono tutti visibili in un unico punto, quindi un fallimento indica la richiesta stessa, non il codice dell'applicazione. Una volta che questo comando funziona, il passaggio a Python è un lavoro meccanico.
La stessa richiesta in Python
Ecco la stessa chiamata implementata con requests. Il corpo della richiesta è lo stesso dict che hai visto nel corpo di curl: l'API non cambia affatto, cambia solo il modo in cui la invii.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
payload = {
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition",
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
response = requests.post(
f"{BASE_URL}/nano-banana-2",
json=payload,
headers=headers,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Perché è scritto così
json=payloadfa sì cherequestsserializzi il dict per te e impostiContent-Type. Puoi comunque passare l'header esplicitamente: non fa male e rende la richiesta autoesplicativa.timeout=120: la generazione delle immagini non è istantanea. Un timeout ampio impedisce al client di arrendersi mentre il modello sta ancora lavorando. Adatta questo valore al tuo caso d'uso.raise_for_status()trasforma le risposte non 2xx in eccezioni, così i fallimenti emergono subito invece di scivolare silenziosamente nel codice che gestisce i risultati.- Le variabili d'ambiente tengono la chiave lontana dal codice sorgente. In produzione, iniettala dall'archivio dei segreti della piattaforma, non da un file
.envche potrebbe essere committato.
Estrarre l'immagine
Il corpo della risposta è JSON. Esaminalo una volta in modo interattivo per capire la struttura esatta, poi estrai esplicitamente il campo dell'immagine:
image_url = data["image_url"] # conferma il nome della chiave su una risposta reale
Se la tua risposta contiene dati base64 anziché un URL, decodificali e scrivili su file:
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(data["image_base64"]))
Non indovinare i nomi dei campi: alla prima chiamata riuscita stampa la risposta grezza e usa i valori effettivamente presenti. Questa singola abitudine previene la maggior parte dei difetti di integrazione.
Text-to-image e image-to-image con immagine di riferimento
Finora abbiamo parlato di text-to-image: inserisci un prompt, ottieni un'immagine. Nano-Banana-2 supporta anche l'image-to-image, in cui fornisci un'immagine di riferimento che il modello usa come guida. Sapere quando cambiare modalità e come cambia il corpo della richiesta è la differenza tra una chiamata riuscita e una rifiutata.
Quando usare ciascuna modalità
- Text-to-image: hai un'idea espressa a parole e nessuna immagine di partenza. È ideale per esplorazione, illustrazione e qualsiasi contenuto generato da zero.
- Image-to-image: hai un'immagine esistente e vuoi una variante, una nuova stilizzazione o una modifica che ne preservi la struttura o il soggetto. È la modalità per iterare sul design, abbinare uno stile visivo o trasformare una foto.
Se il tuo prompt è del tipo "fallo sembrare..." o "mantieni il layout ma...", allora ti serve l'image-to-image.
Come l'immagine di riferimento modifica la richiesta
Endpoint e header restano invariati. Ciò che cambia è il corpo della richiesta: aggiungi un campo per l'immagine di riferimento accanto al prompt. A seconda di come viene fornita l'immagine, quel campo contiene un URL o dati immagine codificati. Tieni presenti queste regole:
- Se passi un link, usa un URL accessibile pubblicamente e diretto. Le pagine che richiedono login o reindirizzamenti autenticati falliscono: l'API deve recuperare direttamente i byte.
- Rispetta i formati previsti. I formati comuni come PNG e JPEG sono sicuri; file insoliti o corrotti sono una causa frequente di richieste rifiutate.
- Controlla i limiti di dimensione prima dell'upload. Le immagini di grandi dimensioni sono spesso la causa di errori nel corpo della richiesta.
- Mantieni il prompt focalizzato. Con un'immagine di riferimento, descrivi la trasformazione che vuoi, non ridurre nuovamente l'immagine di riferimento.
Un corpo di richiesta image-to-image esemplificativo è il seguente:
payload = {
"model": "nano-banana-2",
"prompt": "Same subject, restyled as a graphite sketch with light crosshatching",
"image_url": "https://example.com/your-reference.jpg",
}
Come sempre, conferma i nomi esatti dei campi sulla tua prima risposta riuscita. Il principio è semplice: il text-to-image ha solo il prompt, l'image-to-image aggiunge un'immagine di riferimento verificata alla stessa forma di richiesta. Prima dimostra che il flusso funziona con il text-to-image, poi sovrapponi l'immagine di riferimento.
Gestire gli errori e fare debug delle richieste fallite
I fallimenti delle chiamate a Nano-Banana-2 rientrano in tre categorie. Impara a riconoscerle e potrai risolvere la maggior parte dei problemi in meno di un minuto.
Errori di autenticazione
Se vedi un errore di autenticazione, la chiave non sta arrivando correttamente all'API. Controlla in ordine:
HIAPI_API_KEYè davvero esportata nella shell o nell'ambiente che esegue la richiesta? Eseguiecho $HIAPI_API_KEYper verificarlo.- L'header
Authorizationè presente e ben formato? Sia lo schema che la chiave sono importanti. - La chiave è stata revocata o ruotata nella dashboard?
- Stai accedendo all'URL di base corretto per il tuo account?
401 o 403 significano quasi sempre una di queste quattro situazioni. La chiave in sé raramente è il problema: di solito lo è il percorso che la circonda.
Corpo della richiesta malformato
Gli errori di tipo 400 di solito indicano che l'API non riesce ad analizzare o validare il corpo della richiesta:
- JSON non valido: virgole di troppo, virgolette singole al posto di quelle doppie o caratteri non escapati. Passare l'output di curl a
python -m json.toole costruire il corpo nel codice anziché a mano aiuta. - Campi obbligatori mancanti:
modelepromptsono quelli che si dimenticano più spesso; inviali sempre entrambi esplicitamente. - Campi sconosciuti o non supportati: le API rigorose rifiutano i campi che non riconoscono. Rimuovi tutto il superfluo finché la richiesta non passa, poi aggiungi un elemento alla volta.
- Tipi di valore errati: numeri inviati come stringhe o array passati dove è atteso un singolo valore. Rispetta esattamente i tipi indicati nella documentazione.
Input immagine scadente
Riguarda solo l'image-to-image, ma è il più frustrante quando accade: URL di immagini che richiedono autenticazione, URL dietro reindirizzamenti, URL che restituiscono HTML anziché un'immagine, dimensioni eccessive o formati non supportati. Verifica che l'URL si carichi direttamente nel browser senza login e controlla tipo e dimensione del file rispetto ai limiti prima di inviarlo.
Una sequenza di debug efficace
- Leggi letteralmente il messaggio di errore e il codice di stato: di solito indicano il problema.
- Riproduci la richiesta fallita in curl con i campi minimi, poi aggiungi complessità un passo alla volta.
- Stampa l'intero corpo della risposta prima di elaborarlo; non affidarti alle tue ipotesi sulla sua struttura.
Se la chiamata curl minimizzata riesce mentre la tua applicazione fallisce, il difetto è nel tuo codice, non nell'API. È la linea di demarcazione diagnostica più rapida che puoi tracciare.
Integrarlo nella tua applicazione
Una richiesta funzionante è un buon inizio; un'integrazione affidabile richiede qualcosa in più attorno. Ecco come passare da una chiamata occasionale a qualcosa su cui puoi contare.
Incapsula la chiamata in una funzione
Isola la richiesta in una funzione che riceve il prompt (e facoltativamente l'immagine di riferimento) e restituisce il risultato. Metti header, URL di base e costruzione del corpo della richiesta all'interno di quella funzione, così il resto della codebase non li tocca mai. Quando l'API cambia, devi modificare un solo punto.
Gestisci i tentativi in modo consapevole
La generazione può fallire temporaneamente per motivi indipendenti dal corpo della tua richiesta. Usa tentativi con backoff esponenziale, ma solo per i fallimenti ritentabili: timeout e alcuni errori lato server. Non ritentare mai errori di autenticazione o di validazione del corpo della richiesta; falliranno allo stesso modo ogni volta, aumentando solo il carico. Limita il numero di tentativi, così i problemi persistenti emergono invece di restare sospesi.
Timeout e concorrenza
Imposta un timeout sufficientemente ampio per la generazione ma con un limite massimo, e adattalo dopo aver misurato i tempi di risposta reali. Se devi inviare molte richieste, rispetta limiti di concorrenza ragionevoli invece di inviarle tutte insieme: una coda con un pool di worker è più prevedibile di chiamate parallele illimitate.
Archivia ciò che generi
La risposta ti fornisce l'immagine generata. Copiala tempestivamente nel tuo storage invece di affidarti all'URL restituito, che potrebbe non restare valido a tempo indefinito. Assegna nomi ai file in modo deterministico e registra il prompt e i parametri accanto a ogni output: ti servirà questa tracciabilità quando in futuro itererai sui prompt.
Tieni la chiave lontana dal codice
Leggi la chiave API da variabili d'ambiente o da un gestore di segreti in ogni ambiente. Ruota periodicamente le chiavi. Se una chiave finisce dove non dovrebbe, revocala nella dashboard.
Inizia in piccolo, poi espandi
Fai funzionare un prompt in curl, portalo in Python, aggiungi la gestione degli errori della sezione precedente, e solo dopo costruisci coda e storage attorno. Ogni passo fornisce la prova del passo precedente.
Con una chiamata curl verificata, un client Python corrispondente e le tre categorie di errori gestite, hai il percorso completo dalla prima richiesta all'integrazione in produzione.
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