Blog

Tutoriale

Tutorial sull'API di Nano-Banana-2: usare curl e Python Requests funzionanti tramite hiapi

Nov 10, 2026
Copertina in flat-lay: fogli di carta bianco osso sfalsati a strati con bordi color carbone e un foglio rosso ruggine, 16:9.
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.

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=payload fa sì che requests serializzi il dict per te e imposti Content-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 .env che 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? Esegui echo $HIAPI_API_KEY per 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.tool e costruire il corpo nel codice anziché a mano aiuta.
  • Campi obbligatori mancanti: model e prompt sono 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

  1. Leggi letteralmente il messaggio di errore e il codice di stato: di solito indicano il problema.
  2. Riproduci la richiesta fallita in curl con i campi minimi, poi aggiungi complessità un passo alla volta.
  3. 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.

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