Migrare da Nano Banana 2 a 2.1: cosa cambiare nell'API

Nano Banana 2.1 continua a utilizzare l'interfaccia a task asincroni di HiAPI, quindi la quantità di codice da migrare è contenuta, ma è necessario ricontrollare alcuni vincoli sugli input. Il cambiamento più evidente è il valore di model; sono cambiati anche il numero di immagini di riferimento e la dimensione massima per singolo file. Per i prezzi occorre fare riferimento alla pagina aggiornata e ai record dei task prima della pubblicazione.

Questo articolo si basa sul contratto dell'interfaccia attualmente mostrato nella pagina del modello Nano Banana 2 e nella pagina del modello Nano Banana 2.1. Gli esempi utilizzano la struttura di richiesta presente nella documentazione attuale; prima di spostare il traffico di produzione è necessario verificarli in un account di test con credito disponibile.

La modifica minima è sostituire model

Entrambe le versioni creano il task in modo asincrono:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "A clean e-commerce product photograph of a minimalist amber glass skincare serum bottle with a black dropper cap, blank unlabeled bottle, centered on a white marble pedestal, soft studio lighting, warm white background, no lettering",
      "resolution": "1K",
      "aspect_ratio": "1:1",
      "output_format": "png"
    }
  }'

Se la richiesta originale era di generazione da testo, la migrazione consiste essenzialmente nel modificare model:

- "model": "nano-banana-2"
+ "model": "gemini-nano-banana-2.1"

L'endpoint nella documentazione resta POST /v1/tasks. Dopo che la richiesta è stata accettata, l'endpoint di creazione restituisce un ID del task, utilizzato per il polling o la gestione tramite callback. Il flusso esistente di polling o callback può continuare a essere usato, ma è comunque necessario verificare i campi relativi allo stato del task e al risultato attuali.

Campi che si possono mantenere e limiti da ricontrollare

Il contratto attuale della 2.1 mantiene i campi di input comunemente usati nella versione 2: prompt, image_input opzionale, aspect_ratio, resolution e output_format. Il seguente smoke test con credito disponibile ha accettato sia la generazione da testo sia quella con immagine di riferimento; in fase di passaggio in produzione è comunque necessario verificare il contratto aggiornato in base alle variazioni di versione.

I limiti sulle immagini di riferimento sono cambiati. La pagina di Nano Banana 2 indica un massimo di 14 immagini e 10 MB per file; la pagina della 2.1 indica un massimo di 10 immagini e 30 MB per file. Sostituire solo l'ID del modello e continuare a inviare le vecchie 14 immagini porterebbe la richiesta a superare il nuovo limite. Il client deve verificare il numero in base al nuovo limite e decidere se troncare o avvisare direttamente l'utente.

La pagina del modello 2.1 non rende pubblico l'input mask. In fase di migrazione non aggiungere autonomamente il campo mask, a meno che non venga fornito esplicitamente nella documentazione futura dell'interfaccia. Per la modifica delle immagini si passa l'immagine originale tramite image_input e si specifica nel prompt cosa modificare e quali dettagli preservare.

{
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "Keep the amber glass serum bottle and black dropper cap from the reference image. Place it on a sunlit wooden bathroom counter beside a folded cream linen towel and eucalyptus, preserving the bottle shape and blank label.",
    "image_input": ["https://static.hiapi.ai/blog/gemini-nano-banana-2-1-ecommerce-product-images/studio.jpg"],
    "resolution": "1K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}

Questa richiesta è stata completata con successo nello smoke test con credito disponibile; l'immagine risultante è visibile qui. La pagina della 2.1 attualmente specifica che le immagini di riferimento supportano JPEG, PNG e WebP, con una dimensione massima di 30 MB per file.

Il prezzo va verificato su due livelli

Al momento della verifica della pagina del modello, in data 2026-10-16, i livelli 1K, 2K e 4K di Nano Banana 2.1 mostravano rispettivamente 44, 72 e 116 crediti. Prima di pianificare il budget consultare la pagina dei prezzi aggiornata e la pagina del modello; la rilettura dell'addebito è ancora da verificare in modo indipendente.

Non annotare i numeri di un prezzo promozionale o di una pagina di un determinato account come prezzo fisso a lungo termine. In fase di verifica pre-produzione registrare la risoluzione, l'importo mostrato prima dell'invio e l'addebito effettivo al completamento del task.

Lo stesso prompt con due model ID

Per verificare il percorso di migrazione, abbiamo inviato lo stesso prompt 1K, 1:1 utilizzando separatamente i due model ID pubblici. Entrambe le richieste hanno creato con successo il task e raggiunto lo stato success. I dettagli della bottiglia e del piano d'appoggio nelle due immagini sono diversi, quindi questi risultati sono adatti a verificare il routing e la gestione dei risultati, ma non bastano per classificare la qualità delle immagini né per dimostrare l'identità del prodotto.

Prompt utilizzato nelle due richieste:

A clean e-commerce product photograph of a minimalist amber glass skincare serum bottle with a black dropper cap, blank unlabeled bottle, centered on a white marble pedestal, soft studio lighting, warm white background, no lettering

Routing	Model ID	Risultato
Nano Banana 2	nano-banana-2	1K, 1:1, PNG, task completato con successo
Nano Banana 2.1	gemini-nano-banana-2.1	1K, 1:1, PNG, task completato con successo

Questa verifica di migrazione mostra che il model ID della 2.1 accetta la struttura dei task di generazione da testo presente nella documentazione attuale e restituisce immagini tramite lo stesso flusso asincrono. Le differenze visive in un singolo campione possono essere solo osservazioni, non risultati di un confronto tra modelli.

Checklist prima della pubblicazione

1. Sostituire nano-banana-2 con l'ID esatto della nuova versione: gemini-nano-banana-2.1.
2. Mantenere il flusso asincrono POST /v1/tasks e la gestione esistente dello stato del task.
3. Verificare che image_input sia un array di URL pubblici di immagini, per un massimo di 10.
4. Cambiare l'ipotesi della vecchia versione di 10 MB per file con il limite di 30 MB attualmente indicato nella pagina della 2.1.
5. Mantenere prompt, aspect_ratio, resolution e output_format, rimuovendo i campi non documentati, come mask.
6. Inviare nell'account di test un task di solo testo e un task di modifica con immagine di riferimento, salvando richiesta, ID del task, stato finale, URL del risultato e importo addebitato.
7. Eseguire un confronto con i risultati e la gestione degli errori della versione precedente, poi passare il modello predefinito a tutti gli utenti.

Rilettura dei prezzi e manutenzione successiva

Gli smoke test sopra hanno verificato la struttura delle richieste per la generazione da testo e da immagine, la creazione del task, lo stato finale di successo e l'URL del risultato. L'addebito non è stato riletto in modo indipendente dal completamento del task, quindi per i costi di produzione occorre comunque fare riferimento alla pagina dei prezzi aggiornata e ai record dei task. Se prima della pubblicazione cambiano il contratto o i limiti indicati nella pagina del modello, è necessario ricontrollare.

Domande frequenti

Per migrare a Nano Banana 2.1 è necessario cambiare endpoint?

Attualmente entrambe le pagine dei modelli utilizzano POST /v1/tasks. Modificare prima l'ID del modello, poi verificare la struttura di input e di risposta con richieste reali.

È ancora possibile usare nano-banana-2?

Questo ID indica ancora Nano Banana 2. Per chiamare la 2.1 è necessario usare gemini-nano-banana-2.1.

Dopo la migrazione è ancora possibile inviare 14 immagini di riferimento?

Il limite attualmente indicato nella pagina del modello 2.1 è di 10 immagini. Se il numero viene superato, il client deve ridurre o rifiutare la richiesta.

Per la modifica con immagine di riferimento serve un altro endpoint?

La pagina attuale non prevede un endpoint separato per la modifica. Continuare a usare lo stesso model ID, aggiungere image_input e specificare nel prompt cosa modificare e quali dettagli preservare.

La 2.1 è più economica per tutti gli account?

La pagina pubblica mostra attualmente numeri di crediti standard più bassi per ogni risoluzione, ma i prezzi possono cambiare e la pagina potrebbe essere influenzata dallo stato dell'account o da promozioni. Prima di trarre conclusioni sui costi, verificare sia il prezzo aggiornato sia il record dell'addebito dopo il completamento del task.

Letture correlate

• Guida all'integrazione delle API di Nano Banana 2.1
• Prezzi delle API di Nano Banana 2.1
• Come usare le API di Nano Banana 2

Prova Nano Banana 2.1 nella pagina del modello HiAPI.