Blog

Tutoriale

Come usare nano-banana-2 tramite l'API HiAPI: esempi curl e Python Requests disponibili

Una guida per sviluppatori per collegare nano-banana-2 alla tua pipeline di generazione di immagini

Nov 12, 2026
Immagine di copertina minimalista: su uno sfondo color sabbia calda, barre a gradoni orizzontali in terracotta e marrone si dispongono sfalsate verso il basso come in un grafico a colonne di mercurio.
In questa pagina

Cosa può fare nano-banana-2 per te e quando usarlo

nano-banana-2 è un modello di generazione di immagini richiamabile tramite API HTTP. Invii un prompt, facoltativamente con un'immagine di origine, e ricevi un'immagine generata. Questo è tutto il modello mentale di cui hai bisogno prima di scrivere codice.

Dovresti usare nano-banana-2 quando hai bisogno di generare immagini in modo programmatico all'interno di un prodotto o di una pipeline esistente, anziché tramite una finestra di chat: creazione di materiali di marketing, produzione di miniature e copertine, modifiche iterative basate su un'immagine di partenza, oppure attività batch in cui il numero di immagini è guidato dai tuoi stessi dati. Poiché la sua interfaccia è una normale API request/response, puoi collocarla dietro un worker di coda, un endpoint backend o uno strumento CLI, senza dover introdurre un nuovo SDK per ogni linguaggio.

Due modalità coprono la maggior parte dei casi d'uso:

  • Testo-immagine — descrivi ciò che vuoi con un prompt e ottieni un'immagine.
  • Immagine-immagine — fornisci un'immagine di origine, aggiungi un prompt che descrive la trasformazione e ricevi l'immagine modificata.

Le due modalità hanno la stessa forma di richiesta, quindi un unico wrapper client (che costruiremo più avanti in questo articolo) può gestirle entrambe. Se la tua pipeline genera solo da testo, puoi ignorare completamente il campo image. Se la tua pipeline riguarda la modifica di materiali esistenti, allora immagine-immagine è il tuo punto di ingresso.

Ciò che nano-banana-2 non fa per te: non gestisce i tuoi tentativi ripetuti, i timeout, lo storage o l'idempotenza. Queste sono parti che costruisci attorno alla chiamata — ed è proprio questo il fulcro della maggior parte del resto di questo tutorial, perché chiamare ingenuamente requests.post in un ciclo è la causa più comune di "la demo funziona, la produzione no".

Prima di inviare la prima richiesta

Prima della prima chiamata, devi preparare tre cose.

1. Credenziali della piattaforma

Devi ottenere l'accesso API dalla piattaforma HiAPI e le credenziali assegnate al tuo account. Trattale come segrete: caricarle da variabili d'ambiente o da un gestore di segreti, non commetterle mai nel repository del codice e non incollarle mai negli artefatti pacchettizzati del client. Ogni richiesta di seguito legge la chiave da una variabile d'ambiente, quindi nel codice sorgente non apparirà alcuna informazione sensibile.

export HIAPI_API_KEY="your-key-here"

2. Ambiente client

Con curl ti basta una shell in grado di eseguire curl — gli esempi usano parametri inclusi nella build standard. Con Python ti servono Python 3 e la libreria requests:

python3 -m venv .venv
source .venv/bin/activate
pip install requests

3. Un posto dove archiviare l'output

La generazione di immagini restituisce dati immagine — che siano inline nella risposta oppure come riferimento recuperabile in seguito dipende dalla forma di risposta restituita dal tuo account. Decidi in anticipo se salvare i byte su disco, caricarli su object storage o restituire un URL al chiamante. Pensarci ora evita il classico momento imbarazzante del "funziona nella shell, ma non ho un posto dove mettere il file".

Non è necessario stimare quote o prezzi per iniziare. Il principio generale per una prima integrazione è: invia la richiesta minima valida, verifica di ottenere una risposta valida, poi aggiungi parametri. La sezione successiva fa esattamente questo.

Una richiesta curl minima funzionante

Ecco una chiamata completa di generazione da testo. Endpoint, header e corpo sono le uniche parti variabili: l'endpoint identifica il modello e l'operazione sulla piattaforma HiAPI, gli header trasportano le tue credenziali e il corpo JSON trasporta il payload.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a minimalist isometric workspace, soft daylight, muted palette",
    "n": 1
  }'

Imposta HIAPI_BASE_URL sull'indirizzo base dell'API mostrato nella dashboard del tuo account HiAPI, così non codifichi hard-coded il nome host nello script. Il corpo ha tre campi, tutti importanti:

  • model indica alla piattaforma quale modello eseguire. Mantienilo esplicito anche se altrove usi un valore predefinito; rende i log autoesplicativi.
  • prompt è linguaggio naturale. Sii specifico su soggetto, composizione e stile; i prompt vaghi producono immagini vaghe.
  • n è il numero di immagini richieste per questo prompt. Parti da 1 quando verifichi che il collegamento funzioni.

Una risposta riuscita restituisce i dati immagine nel corpo della risposta. Esaminala prima di scrivere qualsiasi parser: passa l'output a jq o reindirizzalo su file, poi guarda le chiavi di primo livello. Stai verificando due cose — che la richiesta sia stata accettata e dove si trovi effettivamente il payload dell'immagine nella risposta.

Non affrettarti ad aggiungere parametri alla prima chiamata. Una base funzionante che comprendi vale più di un corpo di richiesta enorme che hai copiato. Una volta che questa chiamata restituisce un'immagine, ogni sezione successiva è una sua variante.

La stessa richiesta, scritta in Python

Porta la chiamata curl in Python senza modificare il payload. Mantenere un'unica fonte di verità (un dict) significa che il corpo verificato nella shell è quello che finirai in produzione.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt: str, model: str = "nano-banana-2", n: int = 1,
                   timeout: float = 60.0) -> dict:
    """Invia una richiesta di generazione da testo e restituisce la risposta JSON analizzata."""
    payload = {"model": model, "prompt": prompt, "n": n}
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "a minimalist isometric workspace, soft daylight, muted palette"
    )
    print(result.keys())

Tre dettagli meritano attenzione, perché sono le parti che più spesso vengono tralasciate quando si copia uno snippet.

Imposta sempre un timeout. Senza di esso, una connessione bloccata blocca il tuo worker a tempo indefinito. Il valore sopra è solo un punto di partenza, non una regola ferrea — adattalo in base alla latenza che osservi realmente.

Usa json= invece di data=. Passare un dict a json imposta correttamente il content type e serializza; passare una stringa grezza a data è proprio la causa di quegli errori di formato del corpo che sembrano malfunzionamenti del modello.

Chiama raise_for_status() prima di analizzare. Provare a interpretare con .json() una risposta 4xx come se fosse un campo immagine produce errori a valle confusi. Esponi prima il codice di stato HTTP.

Questa funzione è il wrapper riutilizzabile menzionato prima. La sezione successiva estenderà il suo payload, non lo sostituirà.

Payload per testo-immagine e immagine-immagine

Le due modalità differiscono solo in un punto: se il corpo della richiesta include un'immagine di origine. Tutto il resto — endpoint, header di autenticazione, nome del modello — rimane invariato.

Testo-immagine

{
  "model": "nano-banana-2",
  "prompt": "a minimalist isometric workspace, soft daylight",
  "n": 1
}

Immagine-immagine

{
  "model": "nano-banana-2",
  "prompt": "same scene, but converted to a warm evening palette",
  "image": "<base64-encoded source image>",
  "n": 1
}

Il concetto da interiorizzare: in modalità immagine-immagine, il prompt descrive la trasformazione, non la scena completa da zero. "Converti in una calda palette serale" funziona meglio che ridefinire l'intera immagine, perché l'immagine di origine fornisce già il contenuto.

Due note pratiche sul campo image:

  • Codifica l'immagine di origine nel formato specificato dalla documentazione dell'API per quel campo e mantieni il payload codificato ben al di sotto del tuo budget di dimensione della richiesta. Gli input troppo grandi sono una delle principali cause di rifiuto della richiesta.
  • Se prevedi di accettare upload degli utenti, valida dimensione e formato prima della codifica. Fallire rapidamente dalla tua parte costa molto meno di un round-trip che termina con un 4xx.

Aggiungi un parametro image opzionale al wrapper Python e una sola funzione potrà servire entrambe le modalità:

def generate_image(prompt: str, image: str | None = None, **kwargs) -> dict:
    payload = {"model": "nano-banana-2", "prompt": prompt, **kwargs}
    if image is not None:
        payload["image"] = image
    # ... stessa chiamata di richiesta di prima

Poiché la diramazione è solo un if, il tuo codice chiamante decide la modalità mentre il livello di trasporto resta invariato. Questo è il vantaggio di mantenere un unico wrapper.

Gestire attività asincrone e tentativi ripetuti

La generazione di immagini può richiedere più tempo di una tipica chiamata API JSON. Alcune risposte restituiscono immediatamente l'immagine completata; altre restituiscono un'attività che devi interrogare ripetutamente per ottenere il risultato. Anche se la tua prima chiamata riuscita restituisce immediatamente, progetta per lo scenario di polling — altrimenti, quando una generazione richiede troppo tempo, la tua pipeline si romperà.

Un pattern robusto comprende tre parti: un ciclo di polling con backoff, una scadenza rigida e una strategia di retry che distingua "non ancora pronto" da "fallito".

import time
import requests


def poll_job(job_id: str, base_url: str, api_key: str,
             initial_wait: float = 2.0, max_wait: float = 30.0,
             deadline: float = 300.0) -> dict:
    start = time.monotonic()
    wait = initial_wait
    while True:
        if time.monotonic() - start > deadline:
            raise TimeoutError(f"job {job_id} exceeded deadline")

        response = requests.get(
            f"{base_url}/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30.0,
        )
        response.raise_for_status()
        body = response.json()

        status = body.get("status")
        if status == "succeeded":
            return body
        if status == "failed":
            raise RuntimeError(f"job {job_id} failed: {body}")

        time.sleep(wait)
        wait = min(wait * 2, max_wait)

Il percorso dell'attività e il vocabolario degli stati devono corrispondere a quanto specificato dal riferimento API del tuo account HiAPI — adatta le chiavi sopra alla forma corrispondente, ma conserva la struttura.

Regole per mantenerlo sano in produzione:

  • Backoff esponenziale con tetto. Interrogare ogni 200 ms spreca quota e sovraccarica l'endpoint; raddoppiare l'attesa impostando un tetto si stabilizza vicino al tempo di completamento reale.
  • Limita tentativi totali e tempo totale. deadline non è negoziabile. Un ciclo illimitato è solo in attesa di un guasto causato da una giornata lenta.
  • Riprova solo gli errori ritentabili. Errori di rete transitori e risposte 5xx meritano un nuovo tentativo con jitter; le risposte 4xx no — rinviare un payload malformato fa solo perdere tempo. Usa un numero piccolo e limitato di tentativi (due o tre) e registra ciascuno.
  • Rendi sicuri i retry. Se il tuo endpoint di creazione attività accetta chiavi di idempotenza, invia una chiave stabile per ogni richiesta logica, così i retry non producono generazioni duplicate.

Con scadenza, backoff e un numero limitato di retry, una generazione lenta diventa un evento registrato e gestito, non un worker bloccato.

Debug degli errori che incontrerai realmente

Quando una chiamata fallisce, leggi prima il codice di stato grezzo e il corpo completo della risposta, prima di toccare qualsiasi parametro del modello. Il corpo della risposta di solito indica il problema. Indovinare è più lento che registrare nei log.

Errori di autenticazione

401 o 403 significano quasi sempre una delle seguenti cose: chiave mancante nella variabile d'ambiente, formato dell'header errato oppure credenziali non attive in questo ambiente. Controlla il valore letterale dell'header che stai effettivamente inviando — la mancanza del prefisso Bearer o un newline superfluo introdotto dalla chiave copiata sono cause comuni.

Errori nel payload

Un 400 con un messaggio relativo al corpo della richiesta significa che il JSON stesso è errato: prompt mancante, virgola in eccesso, uso di data= invece di json= in Python, oppure campo image codificato in modo errato. Stampa una volta i byte esatti che stai inviando, controllali, poi rimuovi la stampa.

Input rifiutato

Le richieste immagine-immagine che non superano la validazione di solito riguardano l'immagine di input: troppo grande, formato errato o non decodificabile. Valida dimensione e codifica dalla tua parte prima dell'invio e restituisci un errore chiaro a chi fornisce l'immagine, invece di riprovare.

Timeout e 5xx

Questi rientrano nella categoria ritentabile. Distingui nei log tra timeout di connessione ed errori del server, e verifica che i tuoi retry abbiano un limite — altrimenti un 5xx persistente diventa un ciclo infinito.

Una sequenza di troubleshooting efficace

  1. Registra il codice di stato HTTP e il testo grezzo della risposta per ogni errore.
  2. Verifica prima di tutto il percorso delle credenziali.
  3. Ripeti il payload fallito con curl, rimuovendo il tuo codice client dall'equazione.
  4. Solo dopo, modifica prompt, image o altri parametri del modello.

Se l'errore persiste dopo tutti e quattro i passaggi, cattura l'ID richiesta dalla risposta (o il campo di correlazione equivalente) e allegalo quando contatti il supporto — questo trasforma una segnalazione vaga in qualcosa di tracciabile.

Portarlo in produzione

Prima del rilascio, ripassa questa checklist.

  • Segreti: le chiavi API vengono caricate da variabili d'ambiente o da un gestore di segreti e non compaiono in log, messaggi di errore o artefatti pacchettizzati del client.
  • Timeout: ogni chiamata HTTP — creazione, polling e recupero dell'immagine risultante — ha un timeout esplicito.
  • Limiti: il polling ha una scadenza, i retry hanno un numero massimo di tentativi e il codice distingue gli errori ritentabili da quelli non ritentabili.
  • Osservabilità: per ogni chiamata registra la forma della richiesta (omettendola o applicando un hash se il prompt può contenere dati utente), il codice di stato, la latenza e l'ID di correlazione.
  • Consapevolezza dei costi: la fatturazione segue le dimensioni definite dal tuo account HiAPI, quindi traccia quante generazioni e quanto output produce ogni richiesta, e strumenta i tuoi contatori di utilizzo, così i cicli fuori controllo diventano visibili prima della fattura.
  • Storage: le immagini generate vengono scritte in una posizione persistente — object storage o database — e non lasciate in una directory temporanea che scompare con il container.

Nessuno di questi elementi è specifico di nano-banana-2. Questo è il punto: la chiamata al modello è la parte semplice, tutto ciò che la circonda è normale igiene dei sistemi distribuiti. Costruisci una volta il wrapper, conserva il payload in un unico dict e sia testo-immagine sia immagine-immagine lo ottengono gratuitamente.

Inizia con la chiamata curl, portala nel wrapper Python, aggiungi il ciclo di polling, poi esegui la checklist. Per i dettagli sul modello e il riferimento API più recente, consulta la documentazione di nano-banana-2 sulla piattaforma HiAPI.

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