Come si usa l'API di Nano Banana 2.1? Genera la tua prima immagine in 5 minuti

TL;DR

• Cos'è: l'ultima versione della serie Nano Banana di Google, con un unico ID modello per la generazione da testo e l'editing con immagine di riferimento. È già disponibile su HiAPI: apri la pagina del modello e inserisci il prompt per generare; i nuovi utenti ricevono 200 crediti alla registrazione, sufficienti per circa 4 immagini a 1K.
• Quanto costa: a immagine, 1K $0.022, 2K $0.036, 4K $0.058, circa il 33%–39% in meno rispetto a Nano Banana 2; le immagini di riferimento non costano di più.
• Come chiamare l'API: POST https://api.hiapi.ai/v1/tasks, con model impostato a gemini-nano-banana-2.1; una volta ottenuto il taskId, interroga o attendi il callback, poi scarica da data.output[0].url.

Su Nano Banana 2.1, appena lanciato, le domande più frequenti sono due: cosa sa fare e quanto tempo serve per integrarlo nel proprio progetto. Per la prima vedi i 5 punti qui sotto, per la seconda bastano 5 minuti.

Cosa sa fare Nano Banana 2.1?

• Dal 30% al 40% più economico di NB 2. A parità di risoluzione costa circa il 33%–39% in meno per immagine; a 1K bastano $0.022 e la sintassi dei parametri è identica a NB 2.
• Fino a 10 immagini di riferimento in una volta. Modello, abbigliamento, scenario e foto prodotto si caricano insieme e vengono fusi in un'unica immagine; ideale per cambi d'abito e proposte di visual identity.
• 15 formati, fino a 1:8 e 8:1. Oltre ai classici 1:1, 4:5, 16:9, 21:9, si possono ottenere formati allungati come 1:4, 4:1, 1:8, 8:1: immagini lunghe per pagine di dettaglio e banner in un solo passaggio.
• Tre risoluzioni: 1K, 2K, 4K. 1K per testare i prompt, 2K e 4K per i risultati finali.
• Generazione da testo ed editing condividono lo stesso ID modello. Con solo il prompt è text-to-image, aggiungendo un'immagine di riferimento diventa editing: niente due set di codice.

Servizio fotografico di moda con Nano Banana 2.1, 2K / 16:9, output 2752×1536.

Genera con questo prompt →

Due percorsi per iniziare: prova online o API?

Se vuoi prima vedere il risultato, scegli la prova online; se devi integrarlo in un prodotto, scegli l'API. Entrambi usano lo stesso modello e la stessa struttura di prezzi.

Prova online (circa 1 minuto)

1. Apri la pagina del modello Nano Banana 2.1, oppure clicca direttamente il link sotto l'immagine qui sopra: il prompt verrà compilato automaticamente.
2. Registrati o accedi: i nuovi account hanno 200 crediti inclusi.
3. Scegli formato e risoluzione: un'immagine a 1K costa 44 crediti.
4. Clicca Genera e, se il risultato ti soddisfa, scarica.

Integrazione API (circa 5 minuti)

1. Crea una API Key (sk-...) nella console HiAPI.
2. Crea un task con POST /v1/tasks e recupera data.taskId dalla risposta.
3. Interroga con GET /v1/tasks/{id}, oppure includi callback.url nella richiesta e attendi la notifica.
4. Quando data.status diventa success, scarica l'immagine da data.output[0].url.

Un'immagine a 1K costa $0.022: con $10 ne generi circa 450, abbastanza per mettere a punto il prompt. Per tutti i parametri vedi la documentazione in cinese.

La prima immagine: versione curl

Crea il task:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "A fashion editorial photograph of a model in an ivory linen blazer on a sunlit white-stucco terrace above the Mediterranean, 50mm lens, soft directional light, cinematic color grade",
      "aspect_ratio": "4:5",
      "resolution": "2K",
      "output_format": "png"
    }
  }'

L'ID del task restituito è in data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Interroga il risultato:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

L'unico parametro obbligatorio è prompt. aspect_ratio è auto per default, resolution è 1K per default, output_format può essere jpg o png.

La prima immagine: versione Python

Creazione, polling e download in un unico script: copia, sostituisci la tua Key ed è pronto a girare:

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "gemini-nano-banana-2.1",
    "input": {
        "prompt": "A fashion editorial photograph of a model in an ivory linen blazer on a sunlit white-stucco terrace above the Mediterranean, 50mm lens, soft directional light, cinematic color grade",
        "aspect_ratio": "4:5",
        "resolution": "2K",
        "output_format": "png",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    status = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if status["status"] in ("success", "fail"):
        break
    time.sleep(2)

if status["status"] == "success":
    image_url = status["output"][0]["url"]
    with open("nano-banana-2-1.png", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(status.get("error"))

Editing con immagine di riferimento: basta un campo in più

Aggiungi image_input dentro input e la stessa richiesta diventa un editing. Qui sotto usiamo direttamente lo scatto di moda di prima come immagine di riferimento, cambiando solo il colore della giacca:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "Change the model'\''s blazer to deep burgundy silk while keeping her pose, the terrace, and the lighting unchanged",
      "image_input": ["https://static.hiapi.ai/model-examples/gemini-nano-banana-2.1/2026/10/08/1791466473082-3e77d5c2a1ef0ef6-coastal-fashion-2k.webp"],
      "resolution": "2K"
    }
  }'

image_input accetta fino a 10 URL pubblici, supporta JPEG, PNG e WebP, con un massimo di 30MB per immagine. Nel prompt separa bene "cosa cambiare" e "cosa mantenere": più i dettagli da mantenere sono specifici, più l'immagine originale resta stabile.

3 cose da tenere presenti prima della messa in produzione

1. Sul server usa il callback. Aggiungi al body della richiesta "callback": {"url": "https://yourapp.com/webhook", "when": "final"}: il task notificherà automaticamente al termine, evitando il polling.
2. In caso di timeout non ripetere il POST. Ogni POST /v1/tasks crea un nuovo task e viene addebitato separatamente. Salva prima il taskId e deduplica nel tuo sistema prima di riprovare.
3. Specifica sempre resolution in ogni richiesta. La risoluzione determina direttamente il prezzo unitario: fissala nella richiesta per avere un costo prevedibile.

Errori comuni, uno per riga

• 400 additional properties '<field>' not allowed → nome del campo scritto male, oppure campo di un altro modello (ad esempio image_urls) → confronta con la documentazione e usa il nome corretto, ad esempio image_input.
• 400, con indicazione che il valore di aspect_ratio non è valido → hai passato un formato non presente nella lista → scegli uno dei 15 valori validi elencati nell'errore.
• 401 permission_denied → Key mancante, errata o revocata → controlla l'header Authorization: Bearer sk-... e, se necessario, ricrea la Key nella console.
• Task creato ma stato fail / INVALID_REQUEST → l'URL dell'immagine di riferimento non è raggiungibile o non è un'immagine → usa un JPEG, PNG o WebP accessibile pubblicamente.
• Il link dell'immagine non si apre dopo qualche giorno → i link di output hanno una scadenza → scarica subito il risultato e salva il file.

Per i task falliti, l'importo prenotato viene rimborsato automaticamente per intero.

Domande frequenti

Nano Banana 2.1 può sostituire direttamente NB 2? Sì. I nomi dei parametri sono identici: basta cambiare model in gemini-nano-banana-2.1 per passare al nuovo modello, con un costo per immagine a parità di risoluzione inferiore di circa il 33%–39%. Unica cosa da notare: 2.1 restituisce JPG per default; se ti serve PNG, specifica "output_format": "png".

Le immagini di riferimento costano di più? No. Il prezzo dipende solo dalla risoluzione di output: è identico con 1 o con 10 immagini di riferimento.

Si può ottenere lo sfondo trasparente? I formati di output sono jpg o png; per materiali con sfondo trasparente scegli GPT Image 2.5, che a 1K supporta background: transparent.

Quante immagini si possono generare in una volta? Un task produce un'immagine. Per averne più di una, crea più task in parallelo: il costo è per immagine.

Articoli della serie Nano Banana 2.1

• Pagina del modello Nano Banana 2.1: generazione online, 200 crediti in omaggio alla registrazione
• Quanto costa l'API di Nano Banana 2.1: prezzi unitari 1K/2K/4K e budget mensile
• Nano Banana 2.1 vs GPT Image 2.5: come scegliere in base a budget e caso d'uso
• Raccolta di prompt per Nano Banana 2.1: 5 scenari da copiare per generare subito
• Documentazione di integrazione di Nano Banana 2.1 in cinese: tutti i parametri e i codici di errore

Provalo ora: clicca Genera con questo prompt → sotto lo scatto di moda qui sopra: il prompt è già compilato, scegli 2K, 16:9 e con un clic ottieni lo stesso risultato.