Nano Banana 2 (Gemini 3.1 Flash Image)

Nano Banana 2 è il modello Gemini 3.1 Flash Image di Google. 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

Entrambi gli ID accettano gli stessi parametri. Consulta la pagina del modello per i prezzi attuali.

Esempio rapido

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"}
    }
  }'

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: grounding con Google Search (tools) e contenuti in cache; thinkingLevel non è documentato per questo modello. inlineData non è accettato; passa i media come URL fileData. responseFormat.image.delivery accetta solo INLINE: le immagini finite vengono sempre restituite come URL ospitati.

Dimensioni di output

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

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-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"}}
      ]
    }]
  }'

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 le tariffe correnti. gemini-3.1-flash-image addebita un prezzo fisso per immagine consegnata, indipendentemente da dimensione e prompt. gemini-3.1-flash-image-official addebita in base al consumo: token di input (testo e immagini di riferimento), token di output di testo e ragionamento e token di output di immagine, ciascuno con la propria tariffa. La dimensione dell'immagine è il fattore principale; vedi la tabella sopra.

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-3.1-flash-image",
  "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-3.1-flash-image",
  "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": 27,
      "output_tokens": 1525,
      "total_tokens": 1552,
      "output_tokens_details": {"image_tokens": 1120, "text_tokens": 405, "reasoning_tokens": 0}
    }
  }
}

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.
• Usa 512 o 1K per le bozze e 2K o 4K per le immagini definitive.
• Salva le immagini restituite nel tuo storage se ti serve una copia duratura.

Correlati

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