Como Usar a API Nano Banana 2.1

O Google lançou o Nano Banana 2.1 em 6 de outubro de 2026, e ele já pode ser chamado através da API Gemini como gemini-nano-banana-2.1. É uma atualização do Nano Banana 2 (Gemini 3.1 Flash Image) com melhor qualidade visual, edição no estilo máscara e maior consistência de personagens em várias interações. Ele também custa a metade do preço por imagem em comparação com o Nano Banana 2 em todas as resoluções que eles compartilham.

Este guia o levará de um terminal vazio a uma imagem salva, e então abordará proporções, saída 2K e 4K, edição, mudanças em múltiplas interações, imagens de referência, fundamentação de busca e custo. Cada requisição abaixo pode ser salva e reproduzida no Apidog para que você possa comparar o 2.1 com o modelo que você usa hoje.

Quer o contexto primeiro? Leia O Que É Nano Banana 2.1 para saber o que mudou e o que o Google ainda não publicou.

O que você precisa

Todos os exemplos usam a API Interactions, que é o que a documentação de geração de imagens do Google usa para o 2.1.

Passo 1: Obtenha uma chave de API Gemini

1. Abra o Google AI Studio e faça login.
2. Vá para Obter chave de API e crie uma chave em um projeto do Google Cloud.
3. Ative o faturamento para esse projeto. A página de preços do Google lista o nível gratuito para Nano Banana 2.1 como "Não disponível", então as chamadas de API precisam de um projeto pago.
4. Exporte a chave:

export GEMINI_API_KEY="sua-chave-aqui"

O Google vincula o 2.1 ao playground do AI Studio, o que é útil para testar prompts, mas não publicou o quanto uma conta gratuita pode gerar lá. Nosso guia sobre como usar o Nano Banana 2.1 gratuitamente aborda essa rota, e obter uma chave de API Gemini detalha a configuração da chave.

Passo 2: Gere sua primeira imagem

curl

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {"type": "text", "text": "Crie uma imagem de um prato de nano banana em um restaurante sofisticado com tema Gemini"}
    ]
  }'

A resposta é JSON. A imagem chega como dados base64 dentro de um bloco de conteúdo de imagem, então você vai precisar de um SDK (ou um script) para decodificá-la.

Python

from google import genai
import base64

client = genai.Client()  # lê GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Crie uma imagem de um prato de nano banana em um restaurante sofisticado com tema Gemini",
)

with open("generated_image.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))

interaction.output_image retorna o último bloco de imagem gerado. Seu campo data é base64, então decodifique-o antes de escrever o arquivo.

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-nano-banana-2.1",
  input: "Crie uma imagem de um prato de nano banana em um restaurante sofisticado com tema Gemini",
});

const image = interaction.output_image;
if (image) {
  fs.writeFileSync("nano-banana.png", Buffer.from(image.data, "base64"));
}

Os modelos de imagem Gemini 3 pensam antes de desenhar. O modelo pode produzir até duas "imagens de pensamento" intermediárias enquanto planeja a composição. Você não é cobrado por elas, e o pensamento não pode ser desativado na API.

Passo 3: Defina a proporção, resolução e saída somente de imagem

Use response_format para controlar a saída. Definir "type": "image" retorna apenas a imagem e descarta o texto conversacional, o que mantém as respostas menores e a análise mais simples.

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Uma foto de produto de um moedor de café preto fosco em um balcão de mármore",
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)

Coisas a saber:

• image_size aceita 1K, 2K e 4K. Use K maiúsculo; valores minúsculos como 2k são rejeitados.
• O 2.1 não tem um nível de 512px. Esse pertence ao Nano Banana 2.
• As proporções suportadas incluem 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, além das extremas 1:4, 4:1, 1:8 e 8:1. Uma imagem 16:9 em 2K é 2752x1536; em 4K é 5504x3072.
• Se você quiser texto e uma imagem, passe uma lista: response_format=[{"type": "text"}, {"type": "image"}].

Passo 4: Edite uma imagem existente

Envie sua imagem como um bloco image base64 ao lado da instrução de texto:

with open("living_room.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {"type": "text", "text": "Usando a imagem fornecida de uma sala de estar, mude apenas o sofá azul para ser um sofá chesterfield vintage de couro marrom. Mantenha o restante do cômodo, incluindo as almofadas no sofá e a iluminação, inalterados."},
        {"type": "image", "data": image_b64, "mime_type": "image/png"},
    ],
)

Inpainting estilo máscara sem um arquivo de máscara

Não há upload de máscara separado. Você define a máscara em palavras. O modelo do Google:

Usando a imagem fornecida, mude apenas o [elemento específico] para [novo elemento/descrição]. Mantenha todo o resto na imagem exatamente igual, preservando o estilo, iluminação e composição originais.

Nomeie um elemento, descreva a substituição concretamente e repita o que deve permanecer fixo. Prompts vagos como "deixe o sofá mais bonito" convidam o modelo a redesenhar todo o cômodo.

Passo 5: Itere com edição em múltiplas interações

Múltiplas interações é a maneira recomendada pelo Google para refinar uma imagem. Passe o id da interação anterior como previous_interaction_id e envie apenas a mudança que você deseja:

interaction_2 = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Atualize este infográfico para estar em espanhol. Não altere nenhum outro elemento da imagem.",
    previous_interaction_id=interaction.id,
    response_format={"type": "image", "mime_type": "image/png", "aspect_ratio": "16:9", "image_size": "2K"},
)

Via REST, o mesmo campo vai no corpo: "previous_interaction_id": "<PREVIOUS_INTERACTION_ID>". É aqui que a consistência aprimorada de caracteres em múltiplas interações do 2.1 importa: um personagem ou produto deve permanecer reconhecível ao longo de várias rodadas de edições.

Passo 6: Combine até 14 imagens de referência

Adicione mais blocos image à lista de input. Para o 2.1, o Google documenta até 10 imagens de objetos de alta fidelidade e até 4 imagens de personagens, totalizando 14:

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {"type": "text", "text": "Uma foto de grupo de escritório dessas pessoas, elas estão fazendo caretas engraçadas."},
        {"type": "image", "data": person_1_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_2_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_3_b64, "mime_type": "image/png"},
    ],
    response_format={"type": "image", "aspect_ratio": "5:4", "image_size": "2K"},
)

Imagens de referência são tokens de entrada, e a entrada do 2.1 custa três vezes o que o Nano Banana 2 cobra. Fluxos de trabalho com muitas referências diminuem a diferença de preço, então meça antes de mudar.

Passo 7: Fundamente imagens com a Pesquisa Google

Para imagens que dependem de fatos atuais, como um gráfico de clima ou um evento recente, adicione a ferramenta de pesquisa:

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Uma pintura detalhada de uma borboleta Timareta descansando em uma flor",
    tools=[{"type": "google_search", "search_types": ["web_search", "image_search"]}],
)

{"type": "google_search"} sozinho oferece pesquisa na web. Adicionar image_search permite que o modelo use imagens da web como contexto visual, o que apenas o 2.1 e o Nano Banana 2 suportam. A fundamentação não pode usar imagens de pessoas do mundo real da pesquisa. Se você exibir resultados fundamentados aos usuários, o Google exige que você exiba as search_suggestions retornadas na etapa google_search_result.

Passo 8: Teste no Apidog

Scripts são bons para geração. Para verificar se um prompt, uma chave e um modelo ainda se comportam, uma requisição salva é mais rápida. No Apidog:

1. Crie um ambiente e adicione uma variável GEMINI_API_KEY com sua chave.
2. Crie uma requisição: POST https://generativelanguage.googleapis.com/v1beta/interactions.
3. Adicione o cabeçalho x-goog-api-key: {{GEMINI_API_KEY}}.
4. Cole um corpo JSON com model, input e response_format, então clique em Send.
5. Adicione um script pós-resposta com duas asserções:

pm.test("status is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("response contains an image block", () => {
  const steps = pm.response.json().steps || [];
  const hasImage = steps.some(s =>
    s.type === "model_output" &&
    (s.content || []).some(c => c.type === "image" && c.data)
  );
  pm.expect(hasImage).to.be.true;
});

6. Duplique a requisição e mude model para gemini-3.1-flash-image. Envie ambas com o mesmo prompt.

Agora você tem uma verificação lado a lado do 2.1 contra o Nano Banana 2, com status, tempo e tamanho da resposta mostrados para cada execução. Para uma comparação de recursos mais ampla, veja Nano Banana 2.1 vs Nano Banana 2 vs Pro.

Quanto custa

Nível pago, de acordo com a página de preços do Google em 7 de outubro de 2026:

A saída de imagem para o 2.1 custa $30 por 1M de tokens. Uma imagem 1K são 1.120 tokens, 2K são 1.680 e 4K são 2.520, de onde vêm os preços por imagem. A saída de texto e pensamento custa $7.50 por 1M. A fundamentação de pesquisa inclui 5.000 requisições gratuitas por mês compartilhadas entre os modelos Gemini 3.x, depois $14 por 1.000.

Exemplo prático: 1.000 imagens de produtos em 2K a partir de prompts de texto curtos (cerca de 100 tokens de entrada cada).

• Saída: 1.000 x $0.0504 = $50.40
• Entrada: 100.000 tokens x $1.50 / 1M = $0.15
• Total: cerca de $50.55, mais quaisquer tokens de texto de pensamento

O mesmo trabalho no Nano Banana 2 custa cerca de $101. Através da API Batch, o preço de 2K do 2.1 cai para $0.0252, então o lado da saída cai para $25.20 se você puder esperar. Trabalhos em lote trocam um tempo de resposta de até 24 horas por limites de taxa mais altos. Mais detalhes sobre os preços do Nano Banana 2 estão em nossa análise de preços da API Nano Banana 2.

Erros comuns

Estes são comportamentos genéricos da API Gemini, não erros específicos do 2.1 documentados:

FAQ

Existe um nível gratuito para a API Nano Banana 2.1? Não. O Google lista o nível gratuito da API como "Não disponível". O playground do AI Studio se conecta ao 2.1, mas o Google não publicou um limite gratuito para ele.

O 2.1 é um substituto direto para o Nano Banana 2? Na maioria das vezes. Troque o ID do modelo para gemini-nano-banana-2.1. Você perde o nível de 512px, e os tokens de entrada custam mais, então edições com muitas referências precisam de uma verificação de custo.

As imagens geradas possuem marca d'água? Sim. Todas as saídas incluem uma marca d'água SynthID.

Posso gerar uma imagem a partir de um vídeo? Sim. O 2.1 aceita um bloco de entrada video, como uma URL do YouTube, junto com seu prompt de texto.

O guia antigo da API Nano Banana 2 ainda se aplica? Os conceitos sim. Veja nosso guia da API Nano Banana 2 para o modelo anterior.

Conclusão

O Nano Banana 2.1 promete imagens melhores pela metade do preço por imagem do Nano Banana 2, com a mesma estrutura da API Interactions. Obtenha uma chave faturada, gere uma imagem e salve a requisição no Apidog com asserções de status e imagem. Duplique-a com o ID do modelo antigo, e você saberá em uma tarde se o 2.1 vale a pena a mudança para seus prompts.