Guia da API Nano Banana: chamando nano-banana, nano-banana-2 e nano-banana-pro no HiAPI

O que a família de modelos Nano Banana oferece

A geração de imagens raramente fica em uma única configuração. No início do projeto você precisa de rascunhos rápidos para explorar ideias; mais tarde, precisa de renderizações refinadas para entregar. A família Nano Banana no HiAPI foi construída exatamente em torno dessa realidade: uma interface, três variantes, cada uma ajustada para um ponto diferente da curva entre qualidade e velocidade.

A nomenclatura é intencional. nano-banana é a opção base — use-a quando ainda precisa de feedback visual rápido enquanto molda o prompt ou o layout. nano-banana-2 avança em fidelidade e aderência ao prompt, sendo normalmente a escolha quando a saída está próxima da final mas você ainda quer continuar iterando. nano-banana-pro é a variante de maior fidelidade da família, adequada para renderizações finais em que detalhes e composição são mais importantes.

O que elas compartilham é tão importante quanto o que as diferencia. As três são chamadas pelo mesmo endpoint do HiAPI. Você autentica uma vez, monta a requisição uma vez e, ao trocar, altera apenas o identificador do modelo. Isso significa que uma aplicação pode iniciar a requisição no modelo base e depois reexecutar o mesmo prompt em uma variante mais forte sem alterar o código da camada de transporte.

Uma família assim também mantém sua arquitetura simples. Em vez de integrar um provedor separado para cada nível de qualidade, você mantém um único cliente, um único caminho de tratamento de erros e um único ponto de observação de uso. A escolha do modelo se torna um parâmetro, não uma integração.

Por que uma família e não um único modelo

Etapas diferentes do fluxo de trabalho têm necessidades diferentes. Exploração de prompts, rascunhos de layout e prévias para clientes valorizam velocidade; imagens principais e materiais de marketing valorizam fidelidade. Tratar a escolha do modelo como uma decisão em tempo de execução permite associar cada etapa à variante adequada sem reconstruir o pipeline.

Escolhendo entre nano-banana, nano-banana-2 e nano-banana-pro

Escolha a variante fazendo duas perguntas: quão próxima do final está esta saída e quantas tentativas serão necessárias para chegar lá? O resto decorre disso.

nano-banana: para volume e exploração

Use o modelo base quando ainda estiver decidindo como a imagem deve ser. Reformulação de prompts, testes de estilo e miniaturas de layout se beneficiam de respostas rápidas, e renderizações grosseiras muitas vezes respondem à sua pergunta melhor do que uma descrição. Mantenha-o como padrão durante o desenvolvimento.

nano-banana-2: para iterações próximas da final

Mude para nano-banana-2 quando a composição estiver estável e você estiver refinando detalhes — espaçamento, fidelidade do sujeito, quão fielmente a saída segue o prompt. É a opção intermediária pragmática: aderência claramente mais forte sem passar pelo caminho de maior fidelidade a cada prévia.

nano-banana-pro: para renderizações finais

Reserve nano-banana-pro para as saídas que serão entregues. Imagens principais, fotos de produto e qualquer conteúdo que o cliente examinará de perto merecem a variante mais forte. Não a defina como padrão — deixe-a para a última etapa, mantendo suas iterações exploratórias de baixo custo.

Uma regra de roteamento prática

Uma estratégia simples de escalonamento funciona para a maioria das equipes:

• Use nano-banana como padrão para todos os novos prompts.
• Quando a estrutura estiver correta mas a qualidade insuficiente, promova o prompt para nano-banana-2.
• Depois que o prompt estiver definido, execute a versão final uma vez em nano-banana-pro.

Isso mantém a iteração rápida e previsível, e seus padrões de uso fáceis de entender. A cobrança segue o uso e varia conforme a variante, então confirme as tarifas e limites atuais na documentação ao vivo do modelo em vez de codificar qualquer número diretamente no código.

Padrões de prompt que funcionam em todas as variantes

A coisa mais cara que você pode fazer é escrever prompts que só funcionam em um modelo. Estruture-os de modo que a troca exija a alteração de uma linha.

Prompt em quatro blocos

Escreva cada prompt como quatro partes rotuladas, nesta ordem:

1. Sujeito — o que há na imagem, declarado de forma simples.
2. Estilo — o tratamento visual: fotografia, ilustração, aquarela, renderização 3D.
3. Composição — enquadramento, ângulo de câmera, posicionamento, espaço negativo.
4. Restrições — o que evitar e quaisquer requisitos rígidos.

Um exemplo preenchido:

Subject: a ceramic coffee mug on a wooden desk, steam rising
Style: soft natural light, shallow depth of field, editorial photography
Composition: centered, 50mm equivalent, generous negative space at top
Constraints: no text, no logos, neutral background

Como os blocos são independentes, você pode reforçar o estilo ou relaxar a composição sem reescrever o prompt inteiro — e a mesma estrutura é facilmente compreendida por cada variante da família.

Mantenha os prompts independentes do modelo

Evite formulações que presumam uma característica de um modelo específico. Descreva o resultado que você deseja, não os passos que um modelo concreto deve seguir. Quando precisar comparar variantes, altere apenas o ID do modelo e mantenha o prompt idêntico byte a byte, para que a comparação faça sentido.

Versione prompts como você faz com código

Armazene prompts como strings em um arquivo de configuração ou em uma pequena biblioteca de prompts, indexados por nome e versão. Quando uma variante produzir uma saída melhor após um ajuste fino, registre a alteração. É isso que permite que um prompt migre de nano-banana para nano-banana-pro na entrega sem surpresas.

Restrições negativas são importantes

Se um prompt produzir continuamente texto, logotipos ou objetos indesejados, adicione-os explicitamente ao bloco de restrições. Entre variantes, restrições negativas claras costumam ser mais confiáveis do que uma formulação engenhosa.

Construindo requisições funcionais no HiAPI

Cada variante é chamada pelo mesmo endpoint do HiAPI. Uma requisição tem quatro partes variáveis: a URL base, o cabeçalho de autenticação, o campo do modelo e o payload.

A forma da requisição

Uma chamada mínima de geração de imagem fica assim:

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "Subject: a ceramic coffee mug on a wooden desk, steam rising\nStyle: soft natural light, editorial photography\nComposition: centered, negative space at top\nConstraints: no text, no logos",
    "n": 1
  }'

Mantenha a chave de API em uma variável de ambiente ou em um gerenciador de segredos — nunca no código-fonte. O campo model é a única coisa que você precisa alterar ao trocar de variante, e o campo prompt carrega a estrutura de quatro blocos da seção anterior.

Em Python, a mesma chamada precisa de apenas algumas linhas:

import os, requests

def generate(prompt, model="nano-banana-2"):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": model, "prompt": prompt, "n": 1},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()

O que a resposta contém

A resposta traz o resultado da imagem — normalmente uma URL ou um payload codificado — além de metadados que identificam o modelo que processou a requisição. Leia o campo do modelo de volta e registre-o: é a forma mais barata de saber depois qual variante gerou um determinado ativo.

Confirme os parâmetros antes de entregar

O conjunto exato de parâmetros opcionais varia conforme a variante e evolui com o tempo. Antes de codificar qualquer coisa além de model e prompt, consulte a documentação ao vivo do modelo para obter os nomes atuais dos campos e os valores aceitos. Trate qualquer coisa não documentada como não suportada, em vez de adivinhar.

Lidando com respostas, falhas e novas tentativas

A geração de imagem é uma chamada de rede com um modelo por trás, então planeje as partes que podem falhar.

Valide antes de confiar

Após cada resposta, verifique três coisas: o status HTTP, a presença de um payload de imagem e se o modelo retornado corresponde ao que você solicitou. Qualquer divergência deve falhar explicitamente, em vez de propagar um ativo defeituoso para as etapas seguintes.

Só repita as falhas que merecem nova tentativa

Nem todo erro merece nova tentativa. Um prompt malformado ou um nome de modelo inválido falhará da mesma forma todas as vezes — corrija a requisição. Falhas transitórias, como timeouts, conexões redefinidas e respostas de limite de taxa, merecem nova tentativa.

Use backoff exponencial limitado com jitter:

import time, random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError):
            if attempt == retries - 1:
                raise
            time.sleep((2 ** attempt) + random.random())

Limite o número total de tentativas para que uma requisição defeituosa não entre em loop infinito, e registre o modelo e o hash do prompt de cada tentativa para perceber se uma variante específica está instável.

Faça fallback de forma consciente

Se uma variante falhar continuamente, recorrer a outro membro da família mantém o pipeline vivo. Como as três compartilham a forma da requisição, o fallback é apenas usar um valor diferente de model na nova tentativa. Decida a ordem com antecedência — por exemplo, fazer fallback de nano-banana-pro para nano-banana-2 quando a chamada de alta fidelidade falhar repetidamente — e registre quando o fallback for acionado, para que você perceba padrões.

Torne as falhas visíveis

Valide o payload retornado antes de armazená-lo e emita métricas para novas tentativas e fallbacks. Quando a taxa de erros aumentar, você quer saber antes que um lote de tarefas produza silenciosamente resultados vazios.

Fortaleça antes de entregar

Antes de apresentar a geração de imagens aos usuários, passe por esta lista.

Confirme IDs e parâmetros

Os identificadores de modelo mudam. Verifique novamente os nomes atuais dos modelos da família Nano Banana e confirme cada parâmetro opcional na documentação ao vivo. Não entregue valores que só existem em exemplos antigos.

Centralize a configuração

Coloque IDs de modelo, modelos de prompt e limites de nova tentativa em um único módulo de configuração. Quando você promover o prompt de nano-banana para nano-banana-pro, isso deve ser uma alteração de configuração, não uma alteração de código espalhada por vários arquivos.

Registre o que importa

Para cada chamada, registre o modelo, a versão do prompt, o status da resposta, a latência e se houve nova tentativa ou fallback. Faça hash de prompts longos para manter os logs legíveis. É isso que permite responder “por que esta imagem parece diferente ontem?”.

Monitore o uso ao escalar

Como a cobrança segue o uso, acompanhe o número de chamadas e a combinação de variantes. Cada requisição sendo discretamente promovida a nano-banana-pro pode transformar uma ferramenta de exploração em um problema de custo. Roteie com consciência: variantes baratas para iteração, variantes mais fortes para a saída final.

Teste o endpoint

Escreva um pequeno teste de fumaça que chame cada variante uma vez com um prompt fixo e verifique se a resposta é válida. Execute-o antes de cada release contra a documentação atual, para que mudanças de modelo nunca o peguem de surpresa em produção.

Entregue com um único cliente, uma biblioteca de prompts compartilhada e uma estratégia de roteamento consciente, e a família Nano Banana no HiAPI se tornará sua única dependência para escalar de rascunhos a renderizações finais sem reescrever a integração.