Como usar a API do Nano Banana Pro/Nano Banana 2 — Guia passo a passo para desenvolvedores

Se você pesquisou por “Nano Banana Pro API”, a primeira coisa que pode causar confusão é o nome. O nome do produto é Nano Banana Pro. O nome da API que você realmente usa no código é gemini-3-pro-image. Uma vez esclarecido isso, o restante da configuração fica bem menos complicado.

Use o Nano Banana Pro quando for necessário manter a coesão da imagem: texto legível, detalhes do produto, referências à marca, layouts localizados ou um briefing visual com muitas restrições específicas. Se você ainda estiver testando dez versões da mesma ideia, comece primeiro com o Nano Banana 2 e passe para o Pro quando valer a pena investir mais nessa direção.

Se sua equipe ainda está elaborando prompts em vez de lançar um aplicativo, Espaço de trabalho Nano Banana Pro da GlobalGPT é um recurso prático para comparar resultados antes que um desenvolvedor configure a API oficial. Trata-se de um atalho criativo no fluxo de trabalho, e não um substituto para o console de API do Google, o faturamento, os registros ou os controles corporativos.

Resposta rápida

Para usar o Nano Banana Pro por meio de uma API, crie um projeto no Google AI Studio ou no Google Cloud, gere uma chave de API do Gemini, instale o SDK do Google Gen AI e chame gemini-3-pro-image. Comece com uma solicitação simples de conversão de texto em imagem. Se você ainda estiver verificando o acesso antes de criar uma API, o Guia passo a passo da versão de avaliação gratuita do Gemini 3 Pro é uma leitura complementar útil.

O que é, na verdade, a API Nano Banana Pro

O Nano Banana Pro é o modelo premium de geração de imagens nativas do Google na família de imagens Gemini. Na documentação para desenvolvedores, o Google o denomina Imagem do Gemini 3 Pro. É por isso que a string do modelo parece diferente do nome de marketing.

A API pode gerar uma imagem a partir de texto, utilizar uma ou mais imagens de referência e editar uma imagem existente de acordo com instruções escritas. Isso a torna útil para maquetes de produtos, variantes de anúncios, diagramas, criativos localizados e fluxos de trabalho de imagens em que o texto dentro da imagem precisa permanecer legível; para exploração sem código, a Gerador de imagens GlobalGPT é o lugar mais fácil para testar a direção criativa primeiro.

Nano Banana Pro x Nano Banana 2

A escolha não tem tanto a ver com qual nome soa mais moderno, mas sim com o estágio em que você se encontra no trabalho. “Pro” é para o passe preciso. “Nano Banana 2” é para o ciclo de rascunho desorganizado; se essa rota mais rápida é o que você precisa, leia o Nano Banana: Guia para 2 testes gratuitos antes de projetar todo o fluxo de trabalho com base no Pro.

Configurar a API com os pontos de entrada reais

Para um protótipo, o Google AI Studio costuma ser o caminho mais rápido. Para um aplicativo corporativo, use a configuração do Google Cloud na qual sua equipe já confia, especialmente se você precisar de faturamento compartilhado, controle de acesso, registro de logs ou governança do Vertex AI. Se a decisão sobre o acesso depender realmente dos níveis dos planos do Google, compare as vantagens e desvantagens na Guia comparativo entre o Google AI Plus e o Pro antes de considerar a configuração da API como o único problema.

A documentação pública é o melhor ponto de partida. Ela permite que você confirme se está na página de geração de imagens do Nano Banana, verifique se a página está utilizando o caminho recomendado da API de Interações e acesse, a partir daí, os pontos de entrada da chave de API ou do AI Studio.

1. Crie ou abra um projeto do Google AI Studio ou do Google Cloud.
2. Crie uma chave de API Gemini.
3. Armazene a chave como uma variável de ambiente do lado do servidor.
4. Instale o SDK do Google Gen AI no seu projeto de back-end.
5. Execute um teste em baixa resolução antes de adicionar imagens de referência ou recursos voltados para o usuário.

A página da chave da API também é pública, mas a criação ou visualização de uma chave depende da sua conta do Google e das permissões do projeto. O ponto principal: mantenha essa chave fora do JavaScript do front-end. Um navegador ou aplicativo móvel deve fazer a chamada para o seu back-end, e o seu back-end deve fazer a chamada para o Gemini.

Após o login, a URL direta do AI Studio realmente leva ao Playground com Nano Banana Pro escolhido como gemini-3-pro-image. Nessa explicação, o AI Studio também destacou uma limitação prática: o Nano Banana Pro requer um Plano de IA do Google ou uma chave de API para que o Playground possa executá-lo.

O Obter código Ainda vale a pena conferir o botão neste momento. Ele confirma que você está no fluxo de trabalho do desenvolvedor, mas, se o modelo estiver bloqueado para a conta, o painel de código pode abrir sem um trecho de código completo e executável. Isso é um sinal de configuração, não um bug do prompt.

export GEMINI_API_KEY="SUA_CHAVE_DE_API"

Gerar uma primeira imagem

A primeira solicitação deve ser deliberadamente simples. Você está verificando a autenticação, o acesso ao modelo, o formato da resposta e o tratamento de arquivos. Trabalhos mais complexos com prompts podem esperar até que tudo esteja funcionando corretamente.

from google import genai
from google.genai import types
import os

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

response = client.models.generate_content(
    model="gemini-3-pro-image",
    contents=(
 "Crie uma maquete de produto bem organizada de uma caneca de viagem de aço inoxidável"
 "sobre uma mesa branca. Adicione o rótulo legível: MORNING LAB."
    ),
    config=types.GenerateContentConfig(
 response_modalities=["TEXT", "IMAGE"]
    ),
)

for part in response.candidates[0].content.parts:
    if part.text:
 print(part.text)
    elif part.inline_data:
 with open("nano-banana-pro-output.png", "wb") as f:
 f.write(part.inline_data.data)

Essa solicitação pede uma maquete simples de produto com texto legível. Isso dá a você uma indicação rápida sobre três aspectos importantes no trabalho real: realismo do objeto, composição e se o modelo consegue manter um texto curto nítido. Para ajustar a solicitação sem alterar as credenciais, tente o mesmo briefing em Espaço de trabalho Nano Banana Pro da GlobalGPT Primeiro.

Editar imagens com referências

É na edição baseada em referência que o Nano Banana Pro começa a mostrar seu valor. Em vez de solicitar uma nova imagem do zero, você fornece uma imagem ao modelo e indica exatamente o que pode ser alterado e o que deve permanecer inalterado.

Se você não for um desenvolvedor, leia este bloco como um exemplo de fluxo de trabalho, e não como algo que você precise executar. O nome do arquivo product-reference.png significa simplesmente “a imagem do seu produto atual”. Se sua principal tarefa for comparar modelos de imagem, o conceito mais amplo Teste de alternativas ao Gemini 3 Pro pode ajudar você a decidir se vale a pena fazer a configuração adicional do Pro.

from google import genai
from google.genai import types
from PIL import Image
import os

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
reference = Image.open("product-reference.png")

response = client.models.generate_content(
    model="gemini-3-pro-image",
    contents=[
 reference,
 (
 "Mantenha o formato da caneca, a alça e o posicionamento do logotipo inalterados. "
            "Altere o fundo para uma bancada de cozinha clara, adicione uma luz quente de manhã, "
 "e mantenha todo o texto nítido e legível."
 ),
    ],
    config=types.GenerateContentConfig(response_modalities=["TEXT", "IMAGE"]),
)

Uma boa orientação de edição soa quase como um feedback para um designer: mantenha isso, mude aquilo, não mova o logotipo, mantenha o texto legível. Instruções vagas, como “dê um ar mais sofisticado”, tendem a desperdiçar tentativas, pois deixam muito espaço para o modelo ter que adivinhar.

Preços e controle de custos

Use a página de preços do Google como fonte oficial antes de publicar valores fixos de orçamento. Conforme verificado em 21 de julho de 2026, o Google lista o Nano Banana Pro na categoria Gemini 3 Pro Image e separa o custo de texto/raciocínio do custo de geração de imagens.

Custos de geração de imagens pela API, verificados em 21 de julho de 2026

O modelo de custos prático é simples: faça rascunhos mais baratos e finalize com cuidado. Deixe que o Nano Banana 2 lide com as variações iniciais e, em seguida, envie os prompts e referências mais robustos para o Nano Banana Pro para as imagens finais. Além disso, limite a resolução de acordo com o nível do usuário e evite gerações repetidas quando o prompt não tiver mudado; se você quiser uma linha de rascunho voltada para o produto, Nano Banana 2 em GlobalGPT é a opção mais leve para testar primeiro.

Notas de produção

Quando os usuários puderem gerar imagens a partir do seu produto, você precisará estabelecer limites. As APIs de imagem podem se tornar caras rapidamente, e as falhas precisam ser explicadas sem expor detalhes brutos do provedor. As equipes que ainda estão decidindo quem precisa de acesso pago à IA também podem comparar fluxos de trabalho no modelo de assinatura no ChatGPT Guia para elaboração de plano de negócios.

• Mantenha as chaves no lado do servidor: Não envie a chave API Gemini em um navegador ou cliente móvel.
• Registre informações suficientes para a depuração: ID do modelo, hash do prompt, tamanho da saída, latência, ID do usuário e status do resultado.
• Definir cotas: limitar o número de imagens por usuário, área de trabalho e período de cobrança.
• Tente novamente com cuidado: Tente novamente em caso de falhas temporárias, mas não tente novamente em caso de erros de política ou cota em um loop.
• Defina as regras de armazenamento: Saiba por quanto tempo você mantém as imagens geradas e as referências enviadas.
• Gere mensagens de erro úteis: informe ao usuário se o problema está relacionado ao acesso, ao formato do arquivo, à cota ou à política de solicitações.

Onde o GlobalGPT se encaixa

O GlobalGPT se encaixa melhor antes ou ao lado da compilação da API. Um designer pode comparar o Nano Banana Pro com Nano Banana 2, GPT Image, Flux e outros modelos de imagem em um único espaço de trabalho e, em seguida, repassar o padrão de prompt vencedor ao desenvolvedor.

Para chaves de API oficiais, faturamento, registros, acesso corporativo ou roteamento do Vertex AI, continue usando a plataforma para desenvolvedores do Google. Para uma comparação mais rápida de criativos e menos abas abertas durante o desenvolvimento de prompts, Área de trabalho do gerador de imagens do GlobalGPT pode tornar os primeiros trabalhos menos desajeitados.

PERGUNTAS FREQUENTES

A API Nano Banana Pro é a mesma que a Gemini 3 Pro Image?

Para o trabalho de desenvolvimento, sim. O Google documenta o Nano Banana Pro como Gemini 3 Pro Image, e o ID do modelo na API é gemini-3-pro-image.

Devo usar o Nano Banana Pro ou o Nano Banana 2?

Use o Nano Banana Pro para imagens finais que exijam maior controle, texto legível, referências ou consistência da marca. Use o Nano Banana 2 para rascunhos mais rápidos e iterações mais econômicas.

Posso chamar o Nano Banana Pro diretamente do JavaScript do front-end?

Não. Mantenha a chave da API no lado do servidor, encaminhe as solicitações pelo seu backend e aplique as cotas de usuário antes de enviar as solicitações para a API Gemini.

O GlobalGPT substitui a API oficial do Google?

O No. GlobalGPT é útil para testes rápidos e comparações criativas entre vários modelos, mas as chaves de API oficiais, o faturamento, os registros e os controles corporativos fazem parte da plataforma para desenvolvedores do Google.

Como devo estimar os custos da API Nano Banana Pro?

Utilize a página atual de preços da API Gemini do Google e faça uma estimativa com base no modelo, na resolução de saída e no volume de imagens. Uma estratégia comum de controle de custos é fazer o rascunho inicialmente com o modelo de menor custo e, em seguida, utilizar o Nano Banana Pro para os ativos finais selecionados.