API do Nano Banana 2: como usar em seus projetos

Se você precisa gerar imagens de forma programática, a API do Nano Banana 2, do Google, oferece um dos caminhos mais rápidos de um prompt de texto até um resultado pronto para produção. Disponível diretamente pela infraestrutura de API do Google e por plataformas como o PicassoIA, o nano-banana-2 combina edição conversacional, fusão de múltiplas imagens e fundamentação em busca web em tempo real, em um modelo que você pode chamar com uma requisição HTTP POST padrão. Seja você um desenvolvedor que está criando um pipeline de conteúdo, lançando um recurso de visualização de produtos ou prototipando um app que precisa de imagens com IA sob demanda, veja a seguir como fazer a integração corretamente.

O que o Nano Banana 2 realmente faz

A maioria dos modelos de texto para imagem funciona da mesma forma: você envia um prompt e o modelo devolve uma imagem. O Nano Banana 2 faz isso, mas acrescenta três recursos que mudam a forma como você estrutura sua integração.

Contexto conversacional significa que o modelo lembra o que você gerou na mesma sessão. Você pode descrever um personagem uma vez e, depois, fazer pedidos de acompanhamento como "troque o fundo por um terraço ao pôr do sol" ou "mude a cor da jaqueta para bordô", e o modelo mantém a linha visual sem que você precise repetir a descrição completa a cada vez.

Fusão de múltiplas imagens permite enviar até 14 imagens de referência em uma única requisição. O modelo combina elementos, estilos visuais ou personagens de cada entrada em uma única saída coerente. Isso é especialmente útil em trabalhos de marca, quando você precisa de rostos, logotipos ou fotos de produto consistentes em várias imagens geradas.

Fundamentação em busca web em tempo real conecta o processo de geração ao Google Search. Se o seu prompt faz referência a algo atual, como um evento esportivo recente, um produto recém-lançado ou uma tendência sazonal, o modelo busca contexto visual atualizado na web, em vez de depender apenas de dados de treinamento congelados em uma data de corte.

Contrapartidas entre velocidade e qualidade

O "nano" no nome é preciso. Este modelo é otimizado para vazão. Em prompts comuns, ele gera imagens mais rápido que o flux-1.1-pro ou o sdxl, e a saída padrão de 1K já fica pronta para uso na web. Quando você precisa de mais fidelidade, subir para resolução 2K ou 4K aumenta a latência, mas entrega resultados que se sustentam para impressão ou exibição digital em grande formato.

Como ele se encaixa na linha de imagem do Google

O Google oferece vários modelos de texto para imagem. O Nano Banana 2 fica entre o nano-banana original e o premium nano-banana-pro. Para comparação:

Para a maioria dos cenários de desenvolvimento de aplicações, o nano-banana-2 atinge o ponto ideal.

Configurando o acesso à API

Obtendo suas credenciais

O acesso à API do Nano Banana 2 exige um token de API. Você o obtém pela plataforma Replicate, que hospeda o modelo de propriedade do Google. Depois de criar uma conta e gerar um token, armazene-o como variável de ambiente:

export REPLICATE_API_TOKEN="your_token_here"

Copiar prompt

Nunca coloque tokens diretamente em arquivos de código. Se você estiver implantando em uma plataforma de nuvem, use o serviço de gerenciamento de segredos do seu provedor em vez de arquivos .env.

Entendendo a URL base

A API segue convenções REST padrão. Todas as requisições vão para o endpoint do Replicate, com o identificador do modelo no caminho. O padrão geral:

POST https://api.replicate.com/v1/models/{owner}/{model}/predictions

Copiar prompt

Para o nano-banana-2, isso resulta em:

POST https://api.replicate.com/v1/models/google/nano-banana-2/predictions

Copiar prompt

Toda requisição deve incluir dois cabeçalhos: Authorization: Bearer {token} e Content-Type: application/json.

A anatomia da requisição

Parâmetros obrigatórios

Apenas um parâmetro é obrigatório para gerar uma imagem:

Essa simplicidade é intencional. Uma requisição funcional pode ter apenas cinco linhas de JSON:

{
  "input": {
    "prompt": "A modern studio apartment at golden hour, warm light from west-facing windows, wooden floors, minimal furniture"
  }
}

Copiar prompt

Parâmetros opcionais que mudam os resultados

O controle real está nos parâmetros opcionais:

💡 Definir aspect_ratio como 16:9 e resolution como 2K cobre a maioria dos casos de uso para conteúdo web: landing pages, cabeçalhos de blog e banners para redes sociais.

Lendo a resposta JSON

Uma predição bem-sucedida retorna HTTP 201. O corpo da resposta inclui um ID de previsão e um campo de status:

{
  "id": "xyz123abc",
  "status": "starting",
  "urls": {
    "get": "https://api.replicate.com/v1/predictions/xyz123abc",
    "cancel": "https://api.replicate.com/v1/predictions/xyz123abc/cancel"
  }
}

Copiar prompt

A geração é assíncrona. Você consulta a URL get até que status mude para succeeded, momento em que output contém a URL da imagem ou os dados em base64, dependendo da sua configuração.

Código que funciona agora

Python em menos de 20 linhas

O cliente Python replicate cuida do loop de consulta para você. Instale-o com pip install replicate e depois:

import replicate
import os

client = replicate.Client(api_token=os.environ["REPLICATE_API_TOKEN"])

output = client.run(
    "google/nano-banana-2",
    input={
        "prompt": "A professional product photo of a ceramic coffee mug on a marble surface, soft studio lighting, 4K, photorealistic",
        "resolution": "2K",
        "aspect_ratio": "1:1",
        "output_format": "jpg"
    }
)

# output is a list of FileOutput objects
image_url = str(output[0])
print(image_url)

Copiar prompt

O método client.run() bloqueia até a predição ser concluída e retorna a saída diretamente. Para pipelines de produção, mude para client.predictions.create() e faça a consulta por conta própria, para que você possa processar outras tarefas enquanto as imagens são geradas.

Padrão assíncrono em Node.js

Para desenvolvedores JavaScript, o pacote npm do Replicate oferece a mesma abstração:

import Replicate from "replicate";

const replicate = new Replicate({
  auth: process.env.REPLICATE_API_TOKEN,
});

async function generateImage(prompt, resolution = "1K") {
  const output = await replicate.run("google/nano-banana-2", {
    input: {
      prompt,
      resolution,
      aspect_ratio: "16:9",
      output_format: "jpg",
    },
  });

  return output[0]; // URL to the generated image
}

generateImage("A minimalist home office setup, morning light, wooden desk, single plant")
  .then(url => console.log("Generated:", url))
  .catch(err => console.error("Failed:", err.message));

Copiar prompt

Para pipelines de alto volume, use Promise.all() para disparar várias requisições simultaneamente, em vez de aguardar cada uma em sequência. O Nano Banana 2 lida bem com requisições concorrentes na resolução padrão de 1K.

Como usar o Nano Banana 2 no PicassoIA

Se você prefere uma abordagem sem código ou com pouco código para testar antes de construir sua integração, o PicassoIA dá acesso direto ao nano-banana-2 por uma interface limpa no navegador. Também é uma forma rápida de validar prompts antes de incorporá-los à sua base de código.

Passo 1: abra a página do modelo

Acesse a página do nano-banana-2 no PicassoIA. Você verá o campo de prompt e todas as opções de configuração opcionais dispostas diretamente na página.

Passo 2: escreva um prompt que funcione

O prompt é o único campo obrigatório. Escreva em inglês simples e descritivo. Seja específico sobre iluminação, cenário, clima e assunto. Prompts vagos produzem resultados genéricos. Compare estes dois:

• Fraco: "A woman in a city"
• Forte: "A woman in her 30s with dark hair wearing a tan trench coat, walking through a rainy Paris street at dusk, wet cobblestones reflecting shop lights, shallow depth of field"

A versão mais forte dá ao modelo âncoras: uma pessoa com traços específicos, um cenário, um horário do dia, condições climáticas e uma propriedade fotográfica. O Nano Banana 2 responde bem a esse nível de detalhe.

Passo 3: defina resolução e proporção

Selecione sua resolução no menu suspenso resolution:

• 1K para posts em redes sociais, miniaturas ou iteração rápida
• 2K para landing pages, cabeçalhos de blog e páginas de produto
• 4K para materiais de impressão, exibição em grande formato ou quando você precisa cortar bastante a imagem

Escolha a proporção entre as 15 predefinições disponíveis. Para banners web, use 16:9. Para conteúdo de redes sociais em formato retrato, use 9:16. Para posts quadrados, use 1:1.

💡 Se você estiver trabalhando com imagens de referência, envie-as no campo Image Input. O modelo lê até 14 de uma vez e as usa como contexto visual. Isso é especialmente poderoso para manter a consistência de marca em um conjunto de imagens geradas.

Passo 4: ative a fundamentação web quando fizer sentido

Ative Google Search se o seu prompt envolver acontecimentos atuais, locais reais ou contexto visual sensível ao tempo. Ative Image Search se você quiser que o modelo busque imagens reais da web como referência visual para o seu assunto. As duas opções adicionam uma pequena latência, mas melhoram muito a relevância em prompts contextuais.

Passo 5: gere e baixe

Clique no botão de gerar. O Nano Banana 2 é rápido em 1K, normalmente devolvendo resultados em alguns segundos. Em 4K, espere de 15 a 30 segundos, dependendo da carga do servidor. Baixe sua saída diretamente do painel de resultados.

Erros que você vai encontrar

Códigos de status HTTP comuns

A maioria dos problemas de integração vem de um de quatro pontos: autenticação, corpos de requisição malformados, limites de taxa ou falhas de validação específicas do modelo.

O erro 422 é o mais comum para novas integrações. O corpo da resposta incluirá um campo detail que descreve exatamente qual parâmetro falhou na validação e por quê.

Limites de taxa e como respeitá-los

Contas gratuitas no Replicate têm um limite de requisições por minuto. Para cargas de produção, faça upgrade para um plano pago ou implemente uma fila local que agrupe requisições em vez de disparar todas de uma vez.

Um padrão simples de token bucket em Python:

import time
from collections import deque

class RateLimiter:
    def __init__(self, max_per_minute):
        self.max_per_minute = max_per_minute
        self.requests = deque()

    def wait_if_needed(self):
        now = time.time()
        while self.requests and self.requests[0] < now - 60:
            self.requests.popleft()
        if len(self.requests) >= self.max_per_minute:
            sleep_time = 60 - (now - self.requests[0])
            time.sleep(sleep_time)
        self.requests.append(time.time())

Copiar prompt

Envolva cada chamada de API com rate_limiter.wait_if_needed() antes de fazer a requisição e você nunca terá um 429 em um pipeline de produção.

O que você pode criar com esta API

Mockups de produtos para e-commerce

Em vez de agendar uma sessão de fotografia de produto sempre que você adiciona um SKU, você pode gerar fotos contextualizadas sob demanda. Envie a imagem do seu produto por image_input, descreva o cenário desejado (a bancada de uma cozinha, a mesa de um café, uma cena de estilo de vida ao ar livre) e o nano-banana-2 integra o produto a um ambiente fotorrealista. Para linhas de produtos com várias cores, gere uma cena base e use o recurso de edição conversacional para trocar as cores em pedidos de acompanhamento, sem refazer uma geração completa a cada vez.

Pipelines de marketing de conteúdo

Fluxos de posts de blog que antes exigiam um designer podem passar pela API. No momento da publicação, seu CMS envia o título e o tema do artigo para a API, recebe uma imagem e a anexa ao post automaticamente. Para campanhas ligadas a temas em alta, ative a fundamentação em google_search para que as imagens reflitam o que está acontecendo de fato, e não o que o modelo aprendeu durante o treinamento.

Prototipagem de apps com imagens reais

Imagens de placeholder atrasam as revisões de design. Quando você integra o nano-banana-2 ao seu fluxo de prototipagem, cada tela do seu mockup mostra uma imagem gerada e contextualmente relevante, em vez de caixas cinza. Descreva o conteúdo da seção e deixe a API preenchê-la. As partes interessadas veem layouts realistas e dão feedbacks mais acionáveis.

Fluxos de trabalho com múltiplos modelos

O Nano Banana 2 não precisa trabalhar sozinho. Uma arquitetura comum combina o modelo com outros para processamento sequencial: use o nano-banana-2 para gerar um rascunho rapidamente e, depois, passe a saída para um modelo de super-resolução que faça o upscaling para impressão. Ou gere uma imagem com o nano-banana-2 e, em seguida, use um modelo de inpainting para refinar regiões específicas sem gerar novamente toda a composição.

O PicassoIA dá acesso a todos esses modelos em um só lugar, incluindo o gpt-image-1.5 para tarefas que exigem seguir instruções e o flux-2-pro para saída fotorrealista de alta fidelidade, quando a qualidade máxima é necessária.

Os parâmetros certos para cada projeto

Tipos diferentes de projeto pedem configurações diferentes. Aqui está uma tabela de referência:

Ao trabalhar com imagens de referência via image_input, inclua pelo menos duas imagens se quiser que o modelo capte um estilo visual. Uma única imagem de referência costuma resultar em imitação direta, em vez de adoção de estilo. Várias referências levam o modelo a identificar a linha visual comum entre elas.

Comece a gerar no PicassoIA hoje

A forma mais rápida de ver o que o nano-banana-2 pode fazer para o seu caso de uso específico é rodar alguns prompts antes de escrever qualquer código de integração. O PicassoIA dá acesso imediato ao modelo no link direto, com todos os parâmetros visíveis e ajustáveis em uma única interface.

Teste um prompt que corresponda ao seu caso de uso real de produção. Verifique a saída em 1K primeiro, por velocidade, e depois suba para 2K ou 4K quando tiver um prompt que produza o estilo visual desejado. Quando encontrar uma configuração que funcione, replique-a exatamente nas suas chamadas de API e você obterá resultados consistentes em escala.

Se você precisar de saída de maior fidelidade para trabalho comercial, teste o nano-banana-pro contra o nano-banana-2 com os mesmos prompts e compare os resultados lado a lado. A diferença de qualidade é visível em 4K e importa para impressão ou exibição em grande formato.

Além da geração de imagens, o PicassoIA também oferece mais de 87 modelos de geração de vídeo, ferramentas de super-resolução para fazer upscaling das suas saídas e remoção de fundo para fluxos de e-commerce. Tudo funciona pela mesma interface ou pela API.