Nano Banana Pro no Claude Code: um skill que gera e edita imagens

O Claude Code pode gerar e editar imagens com o Nano Banana Pro por meio de um skill: uma pasta com um arquivo SKILL.md e um script curto que chama a API do SeedRouter. Você digita /nano-banana-pro e descreve a imagem; o Claude escreve o prompt e executa o script, e o script envia a requisição, consulta a tarefa e salva a imagem no seu projeto. A mesma pasta funciona também no OpenAI Codex. O SeedRouter não oferece um skill oficial nem um servidor MCP, então este guia traz um para você copiar. O formato do skill segue a documentação da Anthropic e da OpenAI, conferida em 29 de setembro de 2026.

Como o Claude Code gera imagens com o Nano Banana Pro?

O Claude Code não desenha imagens sozinho. Ele executa comandos, então pode executar um script que chama uma API de imagens. Com um skill instalado, uma requisição funciona assim:

1. Você chama o skill e descreve a imagem, por exemplo /nano-banana-pro a hero image for the pricing page.
2. O Claude transforma sua descrição num prompt do Nano Banana Pro e escolhe o tamanho e a proporção.
3. Ele executa o script. O script envia a requisição para POST https://api.seedrouter.ai/v1/images/generations e recebe um ID de tarefa.
4. O script consulta GET /v1/tasks/{id} a cada poucos segundos até a imagem ficar pronta e então a baixa para uma pasta images/.
5. O Claude informa o caminho do arquivo e depois pode usar a imagem no seu código.

Um script, em vez de só instruções, mantém as chamadas à API exatas: o corpo da requisição, o loop de consulta e o salvamento do arquivo são iguais toda vez, seja qual for o prompt que o Claude escrever.

Do que você precisa antes de começar?

• Uma chave de API do SeedRouter, exportada no terminal em que você inicia o Claude Code:

export SEEDROUTER_API_KEY="your-key"

• Créditos. Cada execução é uma requisição paga. Contas novas começam com um pequeno saldo gratuito, e requisições que falham não são cobradas.
• Python 3. O script usa só a biblioteca padrão, então não há nada para instalar.

O script: enviar, consultar e salvar

Salve isto como scripts/nano_banana_pro.py dentro da pasta do skill:

#!/usr/bin/env python3
import argparse
import json
import os
import pathlib
import sys
import time
import urllib.error
import urllib.request

API = "https://api.seedrouter.ai/v1"
AGENT = "nano-banana-pro-skill/1.0"
MIME = {
    ".jpg": "image/jpeg",
    ".jpeg": "image/jpeg",
    ".png": "image/png",
    ".webp": "image/webp",
    ".heic": "image/heic",
    ".heif": "image/heif",
}
RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]


def call(method, path, body=None):
    request = urllib.request.Request(
        API + path,
        data=None if body is None else json.dumps(body).encode(),
        method=method,
        headers={
            "Authorization": "Bearer " + os.environ["SEEDROUTER_API_KEY"],
            "Content-Type": "application/json",
            "User-Agent": AGENT,
        },
    )
    try:
        with urllib.request.urlopen(request, timeout=60) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        sys.exit(f"HTTP {error.code}: {error.read().decode()}")


def submit(args):
    parts = [{"text": args.prompt}]
    for url in args.ref:
        suffix = pathlib.PurePosixPath(url.split("?")[0]).suffix.lower()
        if suffix not in MIME:
            sys.exit(f"Cannot tell the image type of {url}; use a .jpg, .png, .webp, .heic or .heif URL.")
        parts.append({"fileData": {"mimeType": MIME[suffix], "fileUri": url}})
    image_config = {}
    if args.ratio:
        image_config["aspectRatio"] = args.ratio
    if args.size:
        image_config["imageSize"] = args.size
    generation_config = {"responseModalities": ["IMAGE"]}
    if image_config:
        generation_config["imageConfig"] = image_config
    body = {
        "model": args.model,
        "contents": [{"role": "user", "parts": parts}],
        "generationConfig": generation_config,
    }
    return call("POST", "/images/generations", body)["id"]


def wait(task_id, out_dir, timeout):
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        task = call("GET", "/tasks/" + task_id)
        if task["status"] == "completed":
            out_dir.mkdir(parents=True, exist_ok=True)
            extension = "jpg" if task["output"]["output_format"] == "jpeg" else task["output"]["output_format"]
            for index, image in enumerate(task["output"]["data"]):
                path = out_dir / f"{task_id}-{index}.{extension}"
                download = urllib.request.Request(image["url"], headers={"User-Agent": AGENT})
                with urllib.request.urlopen(download, timeout=120) as response:
                    path.write_bytes(response.read())
                print(path)
            return
        if task["status"] == "failed":
            sys.exit(f"Task {task_id} failed: {task['error']['message']}")
        time.sleep(3)
    sys.exit(f"Task {task_id} is still processing. Resume with --resume {task_id}")


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--prompt")
    parser.add_argument("--ref", action="append", default=[])
    parser.add_argument("--ratio", choices=RATIOS)
    parser.add_argument("--size", choices=["1K", "2K", "4K"])
    parser.add_argument("--model", default="gemini-3-pro-image",
                        choices=["gemini-3-pro-image", "gemini-3-pro-image-official"])
    parser.add_argument("--out", default="images")
    parser.add_argument("--timeout", type=int, default=600)
    parser.add_argument("--resume")
    args = parser.parse_args()
    if args.resume:
        task_id = args.resume
    elif args.prompt:
        task_id = submit(args)
        print(f"task {task_id}", file=sys.stderr)
    else:
        parser.error("--prompt or --resume is required")
    wait(task_id, pathlib.Path(args.out), args.timeout)


if __name__ == "__main__":
    main()

O que ele faz:

• Envia uma única vez. --prompt é o texto, --ref adiciona a URL de uma imagem de referência (repita para adicionar várias) e --ratio e --size definem imageConfig. O corpo da requisição é o formato generateContent do Google com um campo model, como define a referência da API do Nano Banana Pro.
• Mostra o ID da tarefa assim que a tarefa é criada, antes de esperar.
• Consulta e depois salva. Quando a tarefa termina, baixa cada imagem para images/ e mostra cada caminho. Quando a tarefa falha, mostra o motivo.
• Retoma em vez de reenviar. Se a espera acabar, --resume <task id> verifica a mesma tarefa de novo. Um segundo envio seria uma segunda requisição paga.
• Envia um cabeçalho User-Agent. Mantenha essa linha: alguns servidores recusam o padrão do Python e, sem ela, o download pode falhar com um 403.

Você pode testá-lo sozinho antes de o Claude usá-lo:

python3 scripts/nano_banana_pro.py --prompt "A ceramic teapot on a linen tablecloth, soft window light" --ratio 16:9 --size 2K

O skill: o que vai no SKILL.md?

A documentação do Claude Code descreve um skill como um diretório com um arquivo SKILL.md: "frontmatter YAML entre marcadores --- que diz ao Claude quando usar o skill, e conteúdo markdown com as instruções que o Claude segue quando o skill é executado". Arquivos de apoio, como uma pasta scripts/, ficam ao lado.

Salve isto como SKILL.md na mesma pasta:

---
name: nano-banana-pro
description: Generate or edit an image with Nano Banana Pro (gemini-3-pro-image) through the SeedRouter API and save it into the project. Use when the user asks for an image, illustration, icon, poster or edit of an existing image.
argument-hint: "[what the image should show]"
disable-model-invocation: true
---

Create an image for this request: $ARGUMENTS

1. Write one prompt in full sentences: subject, framing, action, setting and style. Put any text that must appear in the image in double quotes and say where it goes. For an edit, say what changes and what must stay the same.
2. Choose --ratio from 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 and --size from 1K, 2K, 4K (4K only for print).
3. Reference images must be public HTTPS URLs ending in .jpg, .png, .webp, .heic or .heif, passed with --ref. If the user points to a local file, ask for a public URL instead. Never send base64.
4. Show the user the prompt and options, and wait for approval. Each run is a paid request.
5. Run: python3 ${CLAUDE_SKILL_DIR}/scripts/nano_banana_pro.py --prompt "..." [--ratio R] [--size S] [--ref URL]
6. If it stops with "still processing", run it again with --resume and the same task ID. Never submit the same request twice.
7. Report the saved file paths. If the task failed, explain the reason and suggest a change to the prompt.

Dois campos importam aqui:

• disable-model-invocation: true significa que só você pode iniciar o skill. A documentação do Claude Code recomenda isso para "fluxos de trabalho com efeitos colaterais ou cujo momento você quer controlar". Cada execução custa dinheiro, então o Claude não deve decidir sozinho gerar uma imagem.
• ${CLAUDE_SKILL_DIR} é substituído pela pasta do próprio skill, para que o script funcione onde quer que você tenha instalado o skill.

Onde colocar o skill e como executá-lo?

O Claude Code carrega skills de dois locais principais:

A pasta pronta fica assim:

nano-banana-pro/
├── SKILL.md
└── scripts/
    └── nano_banana_pro.py

Inicie o Claude Code num terminal em que SEEDROUTER_API_KEY esteja definida e digite o nome do skill seguido do que você quer:

/nano-banana-pro a 16:9 hero image for the pricing page: a calm desk with a laptop, a notebook and a cup of tea, soft morning light, muted green palette, no text

O Claude mostra o prompt e as opções, você aprova e a imagem chega em images/. A menos que você já tenha autorizado o comando, o Claude Code também pede permissão antes de executar o script, o que é uma segunda verificação antes de qualquer cobrança.

Sobre o prompt em si, o guia de prompts do Nano Banana Pro aprofunda estrutura, texto na imagem e referências.

O Codex pode usar o mesmo skill do Nano Banana Pro?

Sim. As duas ferramentas seguem o padrão aberto Agent Skills. A documentação do Codex da OpenAI diz que um skill "é um diretório com um arquivo SKILL.md mais scripts e referências opcionais" e que o arquivo "deve incluir name e description", o que o skill acima tem.

O Codex procura skills em outras pastas:

Copie a pasta para lá ou crie um link simbólico para ela; as duas ferramentas seguem pastas de skills com link simbólico. No Codex, execute /skills ou digite $nano-banana-pro para chamá-lo.

Duas diferenças para saber:

• O caminho do script. ${CLAUDE_SKILL_DIR} é uma substituição do Claude Code. O Codex mostra ao modelo o caminho do arquivo de cada skill, então ele consegue achar scripts/nano_banana_pro.py ao lado do SKILL.md; se ele executar o caminho errado, diga onde está o script.
• O uso automático. disable-model-invocation é um campo do Claude Code. O equivalente no Codex é um arquivo agents/openai.yaml na pasta do skill com allow_implicit_invocation: false em policy, para que o Codex só execute o skill quando você o chamar.

O script precisa de acesso à rede para chegar a api.seedrouter.ai. Se o seu agente roda num sandbox sem rede, libere o acesso à rede para essa sessão.

Como editar imagens que já estão no seu projeto?

O Nano Banana Pro edita a partir de imagens de referência, e a API só as aceita como URLs públicas. Um arquivo no seu disco precisa primeiro ser hospedado em algum lugar, por exemplo no seu próprio bucket de armazenamento, e depois passado com --ref.

As imagens geradas já estão hospedadas: cada tarefa concluída retorna a imagem como URL. Para refinar um resultado, passe essa URL de volta como referência junto com a mudança que você quer:

/nano-banana-pro edit the last image: keep the desk and the laptop, change the tea cup to a glass of water, and make the light warmer

O Claude reutiliza a URL da imagem anterior com --ref e escreve um prompt de edição que diz o que deve continuar igual. Para edições em vários turnos que mantenham o contexto do próprio modelo entre os turnos, a referência da API explica como reenviar os turnos anteriores; o script acima envia um turno por vez.

Se você já usa o GPT Image 2 a partir de um agente de código, GPT Image 2 no Codex e no Claude Code mostra essa configuração, construída em torno de um prompt que você cola no agente.

Perguntas frequentes

Existe um skill ou servidor MCP oficial do Nano Banana Pro do SeedRouter?

Não. O SeedRouter não oferece nenhum. O skill deste guia é uma pasta comum que pertence a você e que você pode alterar, e ele chama a API pública com a sua chave.

Por que o script consulta a tarefa em vez de esperar pela imagem?

No SeedRouter, as requisições do Nano Banana Pro são tarefas: enviar uma retorna um ID de tarefa, e a imagem chega quando a tarefa termina. A consulta mantém as conexões curtas e, se a espera for interrompida, o ID da tarefa continua válido.

Posso usar o mesmo skill para o Nano Banana 2?

Sim, com pequenas mudanças. Troque o valor padrão e as opções de --model no script por gemini-3.1-flash-image e adicione 512 às opções de --size, um tamanho que o Nano Banana 2 aceita e o Pro não. Nano Banana 2 vs Pro vs 2 Lite compara os modelos.

Carregar o skill custa alguma coisa?

Não. O Claude ler o SKILL.md não custa nada no SeedRouter. Cada execução do script é uma requisição, cobrada pela tarifa da página do modelo, e uma tarefa que falha não é cobrada.

Comece a gerar pelo Claude Code

Crie a pasta, exporte sua chave e teste primeiro /nano-banana-pro com uma imagem pequena. Os preços atuais estão na página do Nano Banana Pro, e todos os campos da requisição, na referência da API.