Come usare l'API Nano Banana 2? La tua prima immagine in 5 minuti

TL;DR

• Cos'è: Nano Banana 2, prodotto da Google, usa un unico ID modello nano-banana-2 sia per la generazione da testo sia per l'editing con immagini di riferimento, con un massimo di 14 immagini di riferimento per richiesta. È già disponibile su HiAPI: apri la pagina del modello e inserisci il prompt per generare; i nuovi utenti ricevono 200 crediti alla registrazione.
• Quanto costa: a immagine, 1K $0.036, 2K $0.057, 4K $0.086; le immagini di riferimento non costano di più e i fallimenti vengono rimborsati automaticamente.
• Come chiamare l'API: POST https://api.hiapi.ai/v1/tasks, con model impostato a nano-banana-2; ottieni il taskId, poi interroga o attendi il callback e scarica data.output[0].url.

Cosa può fare Nano Banana 2?

• Un modello, due modalità d'uso. Con solo il prompt è generazione da testo; aggiungendo image_input diventa editing con immagini di riferimento, senza cambiare endpoint o modalità.
• Fino a 14 immagini di riferimento. Puoi inviare insieme foto prodotto da più angolazioni, immagini di modelli e immagini di scenario: ideale per ricreare lo stesso prodotto in scenari diversi, cambi d'abito e set fotografici coordinati per il brand.
• 14 formati fissi più auto. Oltre ai comuni 1:1, 4:5, 16:9, 21:9, ci sono anche 1:4, 4:1, 1:8, 8:1; in caso di dubbio usa il predefinito auto.
• Tre livelli: 1K, 2K, 4K. 1K per provare i prompt, 2K e 4K per le immagini finali; output predefinito in PNG.

Quella sotto è l'immagine di esempio nella pagina del modello Nano Banana 2, generata in 4:3 e 1K:

A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography, 4:3

Genera con questo prompt →

Due percorsi per iniziare: prova online o API?

Se vuoi prima vedere i risultati, scegli la prova online; se devi integrare la funzione nel tuo prodotto, scegli l'API. Entrambi i percorsi usano lo stesso modello e gli stessi prezzi.

Prova online (circa 1 minuto)

1. Apri la pagina del modello Nano Banana 2, oppure clicca direttamente il link sotto l'immagine qui sopra: il prompt verrà compilato automaticamente.
2. Registrati o accedi: il nuovo account include 200 crediti.
3. Scegli formato e risoluzione; al prezzo standard 1K costa 72 crediti per immagine.
4. Clicca Genera e, se sei soddisfatto, scarica.

Integrazione API (circa 5 minuti)

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

1K costa $0.036 per immagine: con $10 puoi generarne circa 277, abbastanza per mettere a punto i prompt. Per tutti i parametri vedi la documentazione in cinese.

La prima immagine: versione curl

Crea il task:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "output_format": "png"
    }
  }'

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

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

Interroga il risultato:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

L'unico campo obbligatorio è prompt. aspect_ratio è predefinito a auto, resolution a 1K, output_format a png (opzionale jpg).

La prima immagine: versione Python

Installa prima requests (python3 -m pip install requests) e imposta HIAPI_API_KEY nel terminale (export HIAPI_API_KEY="sk-YOUR_KEY"). L'esempio crea il task, esegue il polling per un massimo di 10 minuti, poi scarica l'immagine; allo scadere conserva il taskId per continuare a interrogare:

import os
import time
import uuid
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
HEADERS["Idempotency-Key"] = str(uuid.uuid4())  # Save with this business task before submitting.

payload = {
    "model": "nano-banana-2",
    "input": {
        "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
        "aspect_ratio": "4:3",
        "resolution": "1K",
        "output_format": "png",
    },
}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


task_id = task_data(requests.post(API, headers=HEADERS, json=payload, timeout=30))["taskId"]
print(f"taskId: {task_id}", flush=True)  # Save this ID for later queries.

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    task = task_data(requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30))
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        with open("nano-banana-2.png", "wb") as f:
            f.write(image.content)
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task {task_id} failed: {task}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")

Editing con immagini di riferimento: basta aggiungere image_input

Aggiungi image_input dentro input e la stessa richiesta diventa un'operazione di editing. Qui sotto mettiamo un flacone di siero su sfondo bianco su un piano di un bagno:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "Place this exact serum bottle, unchanged, on a white marble bathroom counter next to a folded beige linen towel, soft warm morning window light",
      "image_input": ["https://static.hiapi.ai/blog/nano-banana-ecommerce-product-images-hiapi/shot-1-listing.jpg"],
      "aspect_ratio": "4:3",
      "resolution": "1K"
    }
  }'

image_input è un array di URL, fino a 14, e devono essere link a immagini direttamente accessibili pubblicamente; SVG non è supportato. Indica chiaramente nel prompt "cosa conservare" (this exact serum bottle, unchanged): così etichetta e forma del flacone restano più fedeli. I prompt completi e le immagini finali di questa serie sullo stesso prodotto in scenari diversi sono nella guida completa ai prompt di Nano Banana 2.

3 cose da tenere a mente prima della messa in produzione

1. Sul server usa i callback. Aggiungi al livello superiore del corpo della richiesta "callback": {"url": "https://yourapp.com/webhook", "when": "final"}: il task notificherà automaticamente al termine; il callback arriva sia in caso di successo sia di fallimento, quindi deduplica per taskId.
2. Nei retry includi una chiave di idempotenza. Ogni POST /v1/tasks crea di default un nuovo task e lo addebita separatamente. Aggiungi l'header Idempotency-Key, genera e salva una chiave per lo stesso task di business; dopo un timeout di rete, riprova con lo stesso account, la stessa chiave e un corpo della richiesta identico: il task verrà creato una sola volta.
3. Scarica subito il risultato. I link di output hanno una scadenza: salva prima l'immagine nel tuo storage, poi procedi con le elaborazioni successive.

Errori comuni, uno per riga

• 400 additional properties ... not allowed → nome del campo scritto male, oppure campo di un altro modello (ad esempio image_urls di Nano Banana 2 Lite, o size) → usa image_input e resolution.
• 400, valore di aspect_ratio non valido → hai passato un formato fuori dalla lista → scegli uno dei 15 valori validi.
• 401 permission_denied → Key mancante, errata o revocata → controlla l'header Authorization: Bearer sk-... e, se necessario, ricreala nella console.
• 402 → saldo insufficiente, il task non è stato creato e non viene addebitato nulla → ricarica e riprova.
• status del task uguale a fail → correggi la richiesta in base all'error restituito, non riprovare così com'è; l'importo pre-autorizzato viene rimborsato automaticamente per intero.

Domande frequenti

Come si scrive l'ID del modello? Scrivi nano-banana-2. I nomi dei parametri sono identici a Nano Banana 2.1: basta passare a gemini-nano-banana-2.1 per usare la 2.1.

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

Quante immagini posso ottenere in una volta? Un task produce un'immagine. Per averne più di una, crea più task in parallelo; il costo è per immagine.

Come si ottiene il prezzo promozionale a tempo? Non serve modificare il codice. Lo sconto del 50% per la Festa dei programmatori è valido fino alle 00:00 (ora di Pechino) del 2026-11-09: API e prova online applicano automaticamente il 50% di sconto, quindi 1K costa $0.018 per immagine.

Articoli della serie Nano Banana 2

• Pagina del modello Nano Banana 2: generazione online, 200 crediti in omaggio alla registrazione
• Quanto costa l'API Nano Banana 2: prezzi unitari 1K/2K/4K e budget mensile
• GPT Image 2.5 vs Nano Banana 2: confronto su 9 immagini con gli stessi prompt
• Guida completa ai prompt di Nano Banana 2: 5 scenari da copiare per generare subito
• Prezzi API Nano Banana 2.1: quanto costa meno rispetto a NB 2
• Prezzi API Nano Banana Pro: quanto costa ogni immagine
• Documentazione di integrazione in cinese di Nano Banana 2: tutti i parametri

Prova subito: clicca Genera con questo prompt → sotto l'immagine della foresta pluviale qui sopra: il prompt è già compilato, seleziona 4:3 come formato e 1K come risoluzione, esegui e scarica il risultato; al prezzo standard costa $0.036 per immagine.