Como usar a API do Nano Banana 2: chave, requisição e resultado

Para usar a API do Nano Banana 2, crie uma chave de API, envie o corpo de requisição generateContent do Google com um campo model para um único endpoint e consulte a tarefa retornada até a URL da imagem ficar pronta. Os mesmos passos valem para o Nano Banana Pro e o Nano Banana 2 Lite; só o valor de model muda.

Este guia percorre cada passo com código que funciona e depois mostra como editar com imagens de referência e como passar o trabalho para um agente de código.

Do que você precisa antes da primeira requisição?

1. Uma chave de API. Crie uma na página de chaves de API e mantenha-a no seu servidor. Nunca a coloque em código do navegador.
2. Créditos. Adicione saldo na página de cobrança. Os créditos nunca expiram, e requisições que falham não são cobradas.
3. Um ID de modelo. gemini-3.1-flash-image cobra um preço fixo por imagem; gemini-3.1-flash-image-official cobra por tokens. Veja o guia de preços para escolher.

export SEEDROUTER_API_KEY="your-key"

Como enviar uma requisição ao Nano Banana 2?

Faça um POST da requisição para /v1/images/generations. O corpo é o formato generateContent do Google mais 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"}
    }
  }'

A resposta é uma tarefa, não uma imagem:

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

Se você já chama a API do Google, o corpo que você envia é o mesmo que enviaria ao generateContent. Chamar /v1beta/models/...:generateContent diretamente na SeedRouter não é suportado; use este endpoint.

Como obter a imagem?

Consulte a tarefa a cada poucos segundos até que status seja completed ou failed. Em 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}.")

Uma tarefa concluída traz a URL da imagem em output.data[0].url, além do uso de tokens. Com "responseModalities": ["TEXT", "IMAGE"], qualquer texto que o modelo escrever volta em output.text. Baixe a imagem para o seu próprio armazenamento se precisar dela a longo prazo.

Um tempo limite durante a consulta não significa que a imagem falhou. Guarde o identificador da tarefa e consulte de novo; enviar uma nova requisição significa pagar por uma segunda imagem.

Como editar uma imagem ou usar referências?

Adicione partes fileData ao lado do texto. Cada uma é uma URL pública com seu 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"}}
      ]
    }]
  }'

O Nano Banana 2 aceita até 14 referências por requisição: imagens, vídeos ou PDFs, cada um com menos de 50 MB. As referências precisam ser URLs; inlineData em base64 não é aceito. Se uma URL não puder ser baixada, a tarefa falha e não é cobrada. Para uma edição de continuação, envie os turnos anteriores como entradas user e model e termine com um novo turno user.

Quais configurações mais importam?

A referência da API do Nano Banana 2 lista cada campo e limite. Campos desconhecidos são recusados antes de qualquer cobrança, e o grounding com a Pesquisa Google (tools) ainda não está disponível.

Como deixar um agente de código usar a API do Nano Banana 2?

Um agente de código como Claude Code, Codex ou Cursor pode chamar a API com um comando de shell ou um script curto. A SeedRouter não oferece um servidor MCP nem uma skill empacotada; este prompt é toda a integração. Exporte a chave primeiro e depois cole:

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.

A etapa de aprovação importa: o agente gasta o seu saldo, então ele nunca deve enviar por conta própria.

Perguntas frequentes

Como obter uma chave de API do Nano Banana 2?

Entre na sua conta, abra a página de chaves de API e crie uma chave. A mesma chave funciona para o Nano Banana 2, o Nano Banana Pro, o Nano Banana 2 Lite e os outros modelos da SeedRouter.

A API do Nano Banana 2 suporta requisições em lote?

Envie uma requisição por imagem e consulte as tarefas em paralelo. Cada requisição retorna uma imagem, e cada tarefa é cobrada separadamente.

Quais erros devo tratar?

Um 400 significa que o corpo violou uma regra, como um campo desconhecido ou um tamanho não suportado, e nada é cobrado. Uma tarefa que termina como failed traz uma mensagem de erro e também não é cobrada. O guia de erros lista cada código e quando tentar de novo.

Envie sua primeira requisição

Crie uma chave, adicione um saldo pequeno e execute o exemplo em Python acima, ou teste a mesma requisição sem código no playground do Nano Banana 2. Para prompts complexos, mude o modelo para gemini-3-pro-image para usar o Nano Banana Pro.