Come usare l'API Nano Banana 2: chiave, richiesta, risultato

Per usare l'API Nano Banana 2, crea una chiave API, invia a un unico endpoint il corpo di richiesta generateContent di Google con un campo model e interroga l'attività restituita finché l'URL dell'immagine non è pronto. Gli stessi passaggi valgono per Nano Banana Pro e Nano Banana 2 Lite; cambia solo il valore di model.

Questa guida percorre ogni passaggio con codice funzionante, poi mostra come modificare con immagini di riferimento e come affidare il lavoro a un agente di programmazione.

Cosa ti serve prima della prima richiesta?

Una chiave API. Creala nella pagina chiavi API e tienila sul tuo server. Non inserirla mai nel codice del browser.
Crediti. Aggiungi un saldo nella pagina di fatturazione. I crediti non scadono mai e le richieste non riuscite non vengono addebitate.
Un ID modello. gemini-3.1-flash-image applica un prezzo fisso per immagine; gemini-3.1-flash-image-official addebita i token. Consulta la guida ai prezzi per scegliere.

export SEEDROUTER_API_KEY="your-key"

Come si invia una richiesta a Nano Banana 2?

Invia la richiesta in POST a /v1/images/generations. Il corpo ha la forma generateContent di Google più model:

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

La risposta è un'attività, non un'immagine:

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "processing",
  "created_at": 1790310979
}

Se chiami già l'API di Google, il corpo che invii è lo stesso che invieresti a generateContent. Chiamare direttamente /v1beta/models/...:generateContent su SeedRouter non è supportato; usa questo endpoint.

Come si ottiene l'immagine?

Interroga l'attività ogni pochi secondi finché status non diventa completed o failed. In Python:

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/images/generations",
    headers=headers,
    json={
        "model": "gemini-3.1-flash-image",
        "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
        },
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(f"{API}/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Un'attività completata contiene l'URL dell'immagine in output.data[0].url, più l'utilizzo di token. Con "responseModalities": ["TEXT", "IMAGE"], l'eventuale testo scritto dal modello torna in output.text. Scarica l'immagine nel tuo storage se ti serve a lungo termine.

Un timeout durante il polling non significa che l'immagine sia fallita. Conserva l'identificativo dell'attività e interrogala di nuovo; inviare una nuova richiesta significa pagare una seconda immagine.

Come si modifica un'immagine o si usano riferimenti?

Aggiungi parti fileData accanto al testo. Ognuna è un URL pubblico con il relativo tipo MIME:

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Turn this photo into a watercolor painting. Keep the composition."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

Nano Banana 2 accetta fino a 14 riferimenti per richiesta: immagini, video o PDF, ciascuno sotto i 50 MB. I riferimenti devono essere URL; inlineData in base64 non è accettato. Se un URL non è raggiungibile, l'attività fallisce e non viene addebitata. Per una modifica successiva, invia i turni precedenti come voci user e model e chiudi con un nuovo turno user.

Quali impostazioni contano di più?

Impostazione	Cosa fa
`imageConfig.imageSize`	`512`, `1K`, `2K` o `4K`; `1K` per impostazione predefinita
`imageConfig.aspectRatio`	14 proporzioni da `1:8` a `8:1`; se omesso segue il primo riferimento
`responseModalities`	`["IMAGE"]` per la sola immagine, `["TEXT", "IMAGE"]` per ricevere anche testo
`systemInstruction`	Regole permanenti, come uno stile della casa
`seed`	Riusalo per avvicinarti a un risultato precedente
`mediaResolution`	Quanti token usa ogni riferimento; più basso costa meno su Official

Il riferimento API di Nano Banana 2 elenca ogni campo e limite. I campi sconosciuti vengono rifiutati prima di qualsiasi addebito, e il grounding con Google Search (tools) non è ancora disponibile.

Come far usare l'API Nano Banana 2 a un agente di programmazione?

Un agente di programmazione come Claude Code, Codex o Cursor può chiamare l'API con un comando shell o un breve script. SeedRouter non fornisce un server MCP né una skill pronta; questo prompt è l'intera integrazione. Esporta prima la chiave, poi incolla:

Use the SeedRouter API to generate a Nano Banana 2 image for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, setting, style, what the image is for]
Size: [512 | 1K | 2K | 4K]    Aspect ratio: [e.g. 1:1, 16:9, 9:16]
References: [public image URLs, or none]

Send POST https://api.seedrouter.ai/v1/images/generations with
{"model": "gemini-3.1-flash-image",
 "contents": [{"parts": [{"text": "..."}, {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://..."}}]}],
 "generationConfig": {"responseModalities": ["IMAGE"],
   "imageConfig": {"aspectRatio": "...", "imageSize": "..."}}}
Accepted top-level fields: model, contents, systemInstruction, safetySettings,
generationConfig. References must be fileData URLs (up to 14), never base64.
Do not add tools or any other field.

Before sending, show me the request body and wait for my approval: each
request is charged. Then poll GET https://api.seedrouter.ai/v1/tasks/{id}
every 3 seconds until status is completed or failed. If polling times out,
keep checking the same task; never resubmit. Save output.data[0].url into
./images/ and tell me the file path.

Il passaggio di approvazione è importante: l'agente spende il tuo saldo, quindi non dovrebbe mai inviare richieste di propria iniziativa.

Domande frequenti

Come ottengo una chiave API per Nano Banana 2?

Accedi, apri la pagina chiavi API e crea una chiave. La stessa chiave funziona per Nano Banana 2, Nano Banana Pro, Nano Banana 2 Lite e gli altri modelli su SeedRouter.

L'API Nano Banana 2 supporta le richieste in batch?

Invia una richiesta per immagine e interroga le attività in parallelo. Ogni richiesta restituisce un'immagine e ogni attività viene addebitata separatamente.

Quali errori devo gestire?

Un 400 significa che il corpo ha violato una regola, ad esempio un campo sconosciuto o una dimensione non supportata, e non viene addebitato nulla. Anche un'attività che termina failed riporta un messaggio di errore e non viene addebitata. La guida agli errori elenca ogni codice e quando ritentare.

Invia la tua prima richiesta

Crea una chiave, aggiungi un piccolo saldo ed esegui l'esempio Python qui sopra, oppure prova la stessa richiesta senza codice nel playground di Nano Banana 2. Per i prompt complessi, cambia il modello in gemini-3-pro-image per usare Nano Banana Pro.

Come usare l'API Nano Banana 2: chiave, richiesta e risultato