DEV Community

Cover image for Como Usar a API Nano Banana 2.1
Lucas
Lucas

Posted on Originally published at apidog.com

Como Usar a API Nano Banana 2.1

O Google lançou o Nano Banana 2.1 em 6 de outubro de 2026, disponível na API Gemini como gemini-nano-banana-2.1. Ele atualiza o Nano Banana 2 (Gemini 3.1 Flash Image) com melhor qualidade visual, edição no estilo máscara e maior consistência de personagens entre interações. Nas resoluções compartilhadas, o custo por imagem é metade do Nano Banana 2.

Experimente o Apidog hoje

Neste guia, você vai sair de um terminal vazio até uma imagem salva. Também verá como configurar proporções, saída em 2K e 4K, edição, interações múltiplas, imagens de referência, fundamentação com busca e custos. Salve cada requisição no Apidog para comparar o 2.1 com o modelo usado atualmente.

Quer o contexto antes de começar? Leia O Que É Nano Banana 2.1 para entender o que mudou e o que o Google ainda não publicou.

O que você precisa

Item Valor
URL base https://generativelanguage.googleapis.com/v1beta
Cabeçalho de autenticação x-goog-api-key: $GEMINI_API_KEY
ID do modelo gemini-nano-banana-2.1
Endpoint POST /v1beta/interactions
Resoluções 1K (padrão), 2K, 4K
Entradas Texto, imagens (até 14 referências), vídeo
SDK Python pip install google-genai
SDK JavaScript npm install @google/genai

Os exemplos usam a API Interactions, que é a API utilizada na documentação de geração de imagens do Google para o 2.1.

Passo 1: obtenha uma chave de API Gemini

  1. Abra o Google AI Studio e faça login.
  2. Vá em Obter chave de API e crie uma chave em um projeto do Google Cloud.
  3. Ative o faturamento no projeto. O nível gratuito do Nano Banana 2.1 aparece como “Não disponível” na página de preços do Google, portanto as chamadas de API exigem um projeto pago.
  4. Exporte a chave no terminal: 
export GEMINI_API_KEY="sua-chave-aqui"
Enter fullscreen mode Exit fullscreen mode

O Google vincula o 2.1 ao playground do AI Studio, útil para testar prompts. Porém, não publicou quanto uma conta gratuita pode gerar nesse ambiente. Consulte o guia sobre como usar o Nano Banana 2.1 gratuitamente e o passo a passo para obter uma chave de API Gemini.

Passo 2: gere sua primeira imagem

curl

Envie um POST para o endpoint interactions:

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"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

A resposta é JSON. A imagem chega como base64 em um bloco de conteúdo de imagem, então você precisará decodificá-la antes de salvar o arquivo.

Python

Instale o SDK:

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

Depois, gere e salve a imagem:

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))
Enter fullscreen mode Exit fullscreen mode

interaction.output_image retorna o último bloco de imagem gerado. O campo data contém base64.

JavaScript

Instale o SDK:

npm install @google/genai
Enter fullscreen mode Exit fullscreen mode

Gere e grave a imagem:

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")
  );
}
Enter fullscreen mode Exit fullscreen mode

Os modelos de imagem Gemini 3 pensam antes de desenhar. O modelo pode gerar até duas imagens intermediárias de pensamento para planejar a composição. Essas imagens não são cobradas e o pensamento não pode ser desativado pela API.

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

Use response_format para controlar o formato da resposta. Ao definir "type": "image", a API retorna apenas a imagem, descartando texto conversacional e simplificando o processamento.

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",
    },
)
Enter fullscreen mode Exit fullscreen mode

Pontos importantes:

  • image_size aceita 1K, 2K e 4K. Use K maiúsculo: 2k é rejeitado.
  • O Nano Banana 2.1 não oferece saída de 512px; esse nível pertence ao Nano Banana 2.
  • As proporções incluem 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8 e 8:1.
  • Uma imagem 16:9 em 2K mede 2752x1536; em 4K, 5504x3072.
  • Para receber texto e imagem, use uma lista: 
response_format=[
    {"type": "text"},
    {"type": "image"},
]
Enter fullscreen mode Exit fullscreen mode

Passo 4: edite uma imagem existente

Envie a imagem como um bloco image em base64 junto com a instrução textual:

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",
        },
    ],
)
Enter fullscreen mode Exit fullscreen mode

Inpainting estilo máscara sem arquivo de máscara

Não há upload de máscara separado. Em vez disso, defina a área editável no prompt:

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.

Para reduzir alterações indesejadas:

  1. Nomeie um único elemento.
  2. Descreva a substituição de forma concreta.
  3. Repita o que deve permanecer inalterado.

Evite instruções vagas como “deixe o sofá mais bonito”, pois elas podem fazer o modelo redesenhar todo o ambiente.

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

Para refinar uma imagem, envie o id da interação anterior como previous_interaction_id. Você só precisa fornecer a próxima alteração desejada:

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",
    },
)
Enter fullscreen mode Exit fullscreen mode

Na API REST, envie o mesmo campo no corpo da requisição:

{
  "previous_interaction_id": "<PREVIOUS_INTERACTION_ID>"
}
Enter fullscreen mode Exit fullscreen mode

Essa é a situação em que a consistência aprimorada de personagens entre múltiplas interações do 2.1 importa: personagens e produtos devem permanecer reconhecíveis após várias rodadas de edição.

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

Adicione vários blocos image ao array input. Para o Nano Banana 2.1, o Google documenta:

  • Até 10 imagens de objetos de alta fidelidade.
  • Até 4 imagens de personagens.
  • Máximo total de 14 imagens. 
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",
    },
)
Enter fullscreen mode Exit fullscreen mode

Imagens de referência contam como tokens de entrada. A entrada do 2.1 custa três vezes mais que a do Nano Banana 2, então fluxos com muitas referências reduzem a diferença de preço. Meça esse custo antes de migrar.

Passo 7: fundamente imagens com a Pesquisa Google

Para imagens que dependem de fatos atuais, como clima ou eventos recentes, adicione a ferramenta de busca:

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"],
        }
    ],
)
Enter fullscreen mode Exit fullscreen mode

Usar apenas {"type": "google_search"} habilita busca na web. Ao incluir image_search, o modelo pode usar imagens da web como contexto visual — um recurso suportado pelo 2.1 e pelo Nano Banana 2.

A fundamentação não pode usar imagens de pessoas reais encontradas na pesquisa. Se você mostrar resultados fundamentados aos usuários, o Google exige exibir as search_suggestions retornadas na etapa google_search_result.

Passo 8: teste no Apidog

Scripts funcionam bem para geração, mas uma requisição salva é mais rápida para validar se prompt, chave e modelo continuam funcionando. No Apidog:

  1. Crie um ambiente e adicione a variável GEMINI_API_KEY.
  2. Crie uma requisição: 
   POST https://generativelanguage.googleapis.com/v1beta/interactions
Enter fullscreen mode Exit fullscreen mode
  1. Adicione o cabeçalho: 
   x-goog-api-key: {{GEMINI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode
  1. Cole um corpo JSON com model, input e response_format.
  2. Clique em Send.
  3. Adicione um script pós-resposta para validar status e presença de imagem: 
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((step) =>
    step.type === "model_output" &&
    (step.content || []).some(
      (content) => content.type === "image" && content.data
    )
  );

  pm.expect(hasImage).to.be.true;
});
Enter fullscreen mode Exit fullscreen mode
  1. Duplique a requisição e altere o modelo para gemini-3.1-flash-image.
  2. Execute ambas usando exatamente o mesmo prompt.

Assim, você terá uma comparação lado a lado entre o 2.1 e o Nano Banana 2, com status, tempo e tamanho de resposta por execução. Para uma comparação de recursos mais ampla, consulte Nano Banana 2.1 vs Nano Banana 2 vs Pro.

Quanto custa

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

Modelo Entrada / 1M Imagem 1K Imagem 2K Imagem 4K Lote 1K
Nano Banana 2.1 $1.50 $0.0336 $0.0504 $0.0756 $0.0168
Nano Banana 2 $0.50 $0.067 $0.101 $0.151 $0.034
Nano Banana Pro $2.00 $0.134 $0.134 $0.24 $0.067

A saída de imagem do 2.1 custa $30 por 1 milhão de tokens:

  • Imagem 1K: 1.120 tokens.
  • Imagem 2K: 1.680 tokens.
  • Imagem 4K: 2.520 tokens.

A saída de texto e pensamento custa $7.50 por 1 milhão de tokens. A fundamentação de busca inclui 5.000 requisições gratuitas por mês, compartilhadas entre os modelos Gemini 3.x; depois disso, custa $14 por 1.000 requisições.

Exemplo prático: gerar 1.000 imagens de produto em 2K usando prompts curtos de aproximadamente 100 tokens de entrada.

  • Saída: 1.000 x $0.0504 = $50.40
  • Entrada: 100.000 tokens x $1.50 / 1M = $0.15
  • Total: aproximadamente $50.55, além de tokens de texto de pensamento

O mesmo trabalho no Nano Banana 2 custa aproximadamente $101.

Pela API Batch, o preço de uma imagem 2K no 2.1 cai para $0.0252, reduzindo a saída para $25.20 se você puder esperar. Trabalhos em lote trocam tempo de resposta de até 24 horas por limites de taxa mais altos.

Veja mais detalhes na 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.

Erro Causa provável Correção
400 INVALID_ARGUMENT image_size em minúsculas, proporção não suportada ou input malformado Use 2K, não 2k; confira as proporções suportadas
403 PERMISSION_DENIED Chave inválida ou projeto sem faturamento Verifique a chave e ative o faturamento
404 NOT_FOUND Erro de digitação no ID do modelo Use gemini-nano-banana-2.1 exatamente
429 RESOURCE_EXHAUSTED Limite de taxa atingido Aguarde, tente novamente ou use Batch
500 / 503 Falha temporária do servidor Tente novamente com backoff exponencial
200 sem imagem Prompt bloqueado ou resposta somente de texto Defina "type": "image" e reformule o prompt

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 substitui diretamente o Nano Banana 2?

Na maioria dos casos, sim. Troque o ID pelo gemini-nano-banana-2.1. Você perde o nível de 512px e paga mais por tokens de entrada, então edições com muitas referências exigem 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 vídeo?

Sim. O 2.1 aceita um bloco de entrada video, como uma URL do YouTube, junto com o prompt textual.

O guia antigo da API Nano Banana 2 ainda se aplica?

Os conceitos ainda se aplicam. Consulte o 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, mantendo a mesma estrutura da API Interactions.

Para testar na prática:

  1. Obtenha uma chave com faturamento ativo.
  2. Gere uma imagem.
  3. Salve a requisição no Apidog com asserções de status e imagem.
  4. Duplique a requisição usando o ID do modelo anterior.
  5. Compare os resultados com os mesmos prompts.

Em uma tarde, você consegue verificar se o 2.1 vale a migração para seu caso de uso.

Top comments (0)