Nano Banana 2.1 (Gemini Nano Banana 2.1)

Nano Banana 2.1 è il modello di immagini gemini-nano-banana-2.1 di Google, l'aggiornamento di Nano Banana 2. Invia il corpo di richiesta generateContent di Google con un campo model, conserva l'identificativo dell'attività restituito e interroga quell'attività per ottenere l'immagine finita. Le immagini di riferimento vanno in contents come URL fileData.

ID modello

Consulta la pagina del modello per il prezzo attuale.

Esempio rapido

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

Endpoint

POST https://api.seedrouter.ai/v1/images/generations

Il corpo è la richiesta generateContent di Google con una sola aggiunta: model, perché questo endpoint non indica il modello nel percorso. La risposta contiene un identificativo di attività, non l'immagine finita. Tieni le chiavi API nel codice lato server. Chiamare direttamente /v1beta/models/...:generateContent non è supportato; usa questo endpoint.

Parametri

Categorie di sicurezza: HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT. Soglie: BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE, OFF.

I campi sconosciuti vengono rifiutati. Non ancora disponibili: contenuti in cache e responseFormat; imposta proporzioni e dimensione con imageConfig. inlineData non è accettato; passa i media come URL fileData.

Dimensioni di output

Le altre proporzioni mantengono lo stesso numero di token; ad esempio 16:9 a 1K dà 1376×768 e 21:9 a 4K dà 6336×2688.

Modalità

Non esiste un parametro di modalità separato né un endpoint di modifica.

Per continuare una conversazione, ricostruisci il turno model a partire dalle output.parts dell'attività precedente, nello stesso ordine: una parte di testo diventa {"text": ..., "thoughtSignature": ...} e una parte immagine diventa {"fileData": {"mimeType": "image/<output_format>", "fileUri": <data[image].url>}, "thoughtSignature": ...}. Conserva ogni thoughtSignature esattamente come è stata restituita: è l'URL della firma che abbiamo salvato per te (la firma di un'immagine 4K occupa diversi megabyte), e la ripristiniamo prima che la richiesta raggiunga il modello. Sono accettate solo le firme provenienti dai risultati delle tue attività.

Modificare con un'immagine di riferimento

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "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"}}
      ]
    }]
  }'

Sostituisci l'URL di esempio con una tua immagine accessibile.

Input multimediali

Questa API accetta solo riferimenti tramite URL. Non sono accettati inlineData in base64, URL data: e caricamenti multipart. Il Playground carica i file selezionati nello storage prima di inviarne gli URL.

I riferimenti devono essere URL HTTP(S) pubblici, di meno di 50 MB ciascuno e 100 MB in totale: immagini (image/png, image/jpeg, image/webp, image/heic, image/heif), video (video/mp4, video/mpeg, video/mov, video/avi, video/x-flv, video/mpg, video/webm, video/wmv, video/3gpp) o documenti PDF (application/pdf). mimeType deve corrispondere al file. Gli URL vengono scaricati durante l'elaborazione; un'immagine non raggiungibile fa fallire l'attività, e un'attività fallita non viene addebitata.

Fattori di costo

Consulta la sezione prezzi del modello per il prezzo attuale. gemini-nano-banana-2.1 addebita un prezzo fisso per immagine consegnata, indipendentemente da dimensione, livello di ragionamento e prompt.

Gli addebiti definitivi sono nello storico di utilizzo del tuo account. Le attività fallite non vengono addebitate.

Schema di output

L'invio restituisce un riferimento all'attività:

{
  "id": "task_...",
  "model": "gemini-nano-banana-2.1",
  "status": "processing",
  "created_at": 1790310979
}

Interrogare l'attività

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

Interroga ogni pochi secondi finché status non diventa completed o failed. Un timeout di rete durante il polling non significa che la generazione sia fallita: conserva l'identificativo dell'attività e riprendi il controllo. Non creare un'altra attività per verificare l'avanzamento.

Esempio di polling completo

Esegui questo dopo l'esempio di invio in Python qui sopra.

import time

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        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}.")

Attività completata

{
  "id": "task_...",
  "model": "gemini-nano-banana-2.1",
  "status": "completed",
  "created_at": 1790310979,
  "finished_at": 1790311001,
  "output": {
    "created": 1790310999,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.jpg"}],
    "output_format": "jpeg",
    "usage": {
      "input_tokens": 22,
      "output_tokens": 2297,
      "total_tokens": 2319
    }
  }
}

Lo streaming (streamGenerateContent) non è supportato; i risultati vengono consegnati tramite l'attività.

Errori

Le richieste rifiutate prima della creazione di un'attività restituiscono un errore HTTP con un oggetto error. Un'attività che fallisce dopo l'accettazione restituisce HTTP 200 all'interrogazione, con status: "failed" e un oggetto error. Un'immagine bloccata dai filtri di sicurezza del modello fallisce con content_policy_violation; una risposta senza immagine fallisce con no_output.

Vedi il catalogo errori comune per codici, stati HTTP e indicazioni sui tentativi.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

Se è l'invio stesso ad andare in timeout, controlla lo storico delle attività prima di inviare di nuovo: la prima richiesta potrebbe essere già stata accettata.

Suggerimenti

• Descrivi soggetto, ambientazione, illuminazione e stile con frasi complete.
• Per una modifica, indica cosa deve cambiare e cosa deve restare invariato.
• Il prezzo è lo stesso a ogni dimensione, quindi chiedi quella che ti serve: 1K per le bozze, 2K o 4K per le immagini definitive.
• Metti tra virgolette le parole esatte da mostrare nell'immagine e tienile brevi.
• Usa il ragionamento MINIMAL per bozze più rapide e HIGH per layout densi come le infografiche.
• Salva le immagini restituite nel tuo storage se ti serve una copia duratura.

Correlati

• Playground e prezzi di Nano Banana 2.1
• Scarica l'OpenAPI
• Markdown copiabile