Tutorial
Como usar o Nano-Banana pela API do HiAPI: curl, Python e requisições executáveis
Nesta página
O que o Nano-Banana oferece aos desenvolvedores como API
O Nano-Banana é um modelo de geração de imagens disponibilizado publicamente pela API do HiAPI. Você envia um prompt — e, se necessário, uma ou mais imagens de referência — e recebe a imagem gerada. O modelo mental geral é simples assim. Sem hospedar o modelo localmente, sem GPU, sem aprender um SDK adicional: a autenticação, o encapsulamento de requisições e o mecanismo de tarefas assíncronas que você usa com outros modelos do HiAPI valem igualmente aqui.
Antes de escrever código, vale a pena deixar claro o que o endpoint de geração de imagens é e o que não é. Ele é um endpoint criativo: o mesmo prompt pode produzir resultados diferentes em execuções distintas, e você deve projetar seu pipeline para tolerar isso. Ele não é uma transformação determinística como redimensionamento ou conversão de formato. Se você precisa de reprodutibilidade exata em nível de pixel, armazene em cache as saídas que você aprovou, em vez de supor que uma nova geração dará o mesmo resultado.
Uma integração típica tem três fases:
- Enviar uma requisição de geração com o prompt e quaisquer entradas opcionais.
- Aguardar a conclusão da tarefa gerada, porque a geração de imagens leva mais tempo do que uma simples conclusão de texto.
- Obter a saída, armazená-la e decidir se aceita ou ajusta o prompt e tenta novamente.
Há duas coisas que vale a pena decidir desde o início, porque afetam todo o resto: se o seu prompt é apenas texto ou usa imagens de referência (o que altera o payload da requisição), e se você precisa manter consistência de personagem entre várias gerações (o que quase sempre significa usar imagens de referência). As seções a seguir expandem a partir da estrutura da requisição, e você pode ajustar os exemplos enquanto lê.
Anatomia de uma requisição ao Nano-Banana
Toda requisição ao Nano-Banana via HiAPI tem o mesmo esqueleto. O que muda é o payload.
Endpoint e autenticação
A requisição vai para a URL base do HiAPI, e o modelo específico é especificado no payload da requisição, não em uma URL upstream montada manualmente. Você autentica levando sua chave de API no cabeçalho Authorization. Mantenha a chave em uma variável de ambiente — nunca embutida no código-fonte nem commitada no repositório.
Nome do modelo
O identificador do modelo é um campo no corpo JSON da sua requisição. Trate-o como uma string que deve ser copiada literalmente da lista de modelos, e não algo que você monta por conta própria, para que mudanças de nomenclatura não quebrem seu código silenciosamente.
Payload do prompt
Você precisa enviar pelo menos um prompt de texto descrevendo a imagem desejada. Aqui, a qualidade do prompt afeta a qualidade da saída muito mais do que qualquer outro campo. Seja específico sobre assunto, composição, iluminação e estilo. Prompts vagos geram imagens vagas, e nenhuma configuração de parâmetro salva um prompt que não expressa o que você realmente precisa.
Imagens de referência opcionais
Se você incluir imagens de referência, elas fazem parte do mesmo corpo da requisição — normalmente fornecidas como URLs de imagem ou dados de imagem codificados, dependendo do formato que o modelo aceita. Imagens de referência podem ancorar coisas como o rosto de um personagem, o vestuário ou o estilo artístico geral. Omita-as no modo texto-para-imagem puro; inclua-as quando a saída precisar se parecer com um objeto específico.
Campos relacionados à saída
Alguns campos afetam a forma do resultado, não o conteúdo: por exemplo, o tamanho de saída solicitado ou a proporção. É melhor tratá-los como valores solicitados, não como garantias — o modelo pode retornar dimensões ligeiramente diferentes. O código downstream deve ler as dimensões realmente retornadas, em vez de supor que o que você pediu é o que você recebeu.
A seguir, a estrutura conceitual, com valores de placeholder:
{
"model": "<nano-banana-model-id>",
"prompt": "Uma raposa-vermelha sentada em capim alto na hora dourada, profundidade de campo rasa",
"reference_images": [],
"size": "1024x1024"
}
Consulte a documentação de parâmetros do modelo para conhecer os nomes exatos de campos e formatos aceitos — a estrutura acima é apenas o padrão genérico e não substitui a documentação normativa.
Requisição curl executável
A maneira mais rápida de confirmar que a chave funciona e o payload é válido é fazer uma chamada curl. Primeiro, configure o ambiente:
export HIAPI_API_KEY="your-api-key-here"
Depois, envie a requisição de geração:
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<nano-banana-model-id>",
"prompt": "Uma raposa-vermelha sentada em capim alto na hora dourada, profundidade de campo rasa",
"size": "1024x1024"
}'
O que cada parte faz:
- URL — o caminho de geração de imagens do HiAPI. Uma URL base atende todos os modelos; o modelo é especificado no corpo da requisição.
Authorization— sua chave, lida do ambiente, para que não vá parar no histórico do shell nem no controle de versão.Content-Type— deve serapplication/json; um erro comum de iniciante é esquecer de defini-lo e receber erros de parsing.- Corpo da requisição — o payload JSON da seção anterior, contendo o prompt que você realmente quer.
Interpretando a resposta
A resposta informa o que aconteceu. Dois tipos de resultado merecem atenção:
- Resultado síncrono — algumas chamadas retornam diretamente os dados da imagem ou a URL da imagem. Se você receber uma URL, baixe e armazene o quanto antes, em vez de contar com a disponibilidade dela a longo prazo.
- Identificador de tarefa — se a geração for assíncrona, a resposta incluirá um identificador para consultar o status. Esse é o tema da seção de assincronia abaixo.
Se você quiser ver a linha de status HTTP e os cabeçalhos da resposta além do corpo, adicione -i ao comando curl — em caso de erro, isso é muito útil para distinguir se o problema é de autenticação ou de payload.
A mesma chamada em Python
Fora de scripts descartáveis, use Python. A biblioteca requests mantém o exemplo leve em dependências e deixa a camada HTTP explícita e visível.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
payload = {
"model": "<nano-banana-model-id>",
"prompt": "Uma raposa-vermelha sentada em capim alto na hora dourada, profundidade de campo rasa",
"size": "1024x1024",
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Alguns hábitos que vale a pena cultivar desde o começo:
- Defina timeout. A geração de imagens é lenta; sem timeout, seu processo de trabalho pode travar indefinidamente. Para chamadas síncronas, um timeout generoso é um ponto de partida razoável, mas ajuste conforme sua carga.
- Use
raise_for_status(). Ele converte respostas 4xx e 5xx em exceções capturáveis, em vez de silenciosamente tratar o corpo de erro como resultado. - Encapsule em funções. O trecho acima é um script; em um serviço, você vai querer uma função que receba o prompt e devolva os dados da imagem ou o identificador da tarefa, para que o restante do código não precise se preocupar com detalhes de HTTP.
Se a resposta contiver uma URL de imagem, baixe e armazene imediatamente:
for item in data.get("data", []):
url = item.get("url")
if url:
img = requests.get(url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
A fonte de dados real da sua aplicação deve ser o seu próprio armazenamento — não uma URL remota temporária.
Tratando tarefas assíncronas
A geração de imagens costuma levar mais tempo do que um único ida-e-volta HTTP deve manter a conexão aberta. Modelos do HiAPI que funcionam assim retornam um identificador de tarefa quando você envia a requisição, e então você consulta o endpoint de status da tarefa até o trabalho concluir. Esse padrão vale para todos os modelos assíncronos da plataforma, então aprenda uma vez só.
Envie primeiro, consulte depois
Seu POST inicial retorna algo como um ID de tarefa. Depois, você consulta o endpoint de status com esse ID. A lógica de que você precisa é:
import time
def poll_task(task_id, api_key, interval=2, max_wait=300):
headers = {"Authorization": f"Bearer {api_key}"}
deadline = time.time() + max_wait
while time.time() < deadline:
r = requests.get(
f"https://api.hiapi.ai/v1/tasks/{task_id}",
headers=headers,
timeout=30,
)
r.raise_for_status()
body = r.json()
status = body.get("status")
if status in ("succeeded", "completed", "failed", "error"):
return body
time.sleep(interval)
raise TimeoutError(f"A tarefa {task_id} não foi concluída em {max_wait} segundos")
Três regras que evitam dores de cabeça
- Sempre limite o tempo total de espera. Trabalhos que nunca terminam não podem travar seu processo de trabalho. O
max_waitacima é sua via de saída. - Faça backoff. Intervalos curtos e fixos funcionam para uso interativo; para trabalhos em lote, aumente o intervalo conforme o tempo de espera cresce, para não bombardear o endpoint de status.
- Verifique o estado terminal.
succeededsignifica que você pode ler a saída;failedsignifica que você deve ler o payload de erro, e não tentar de novo cegamente. Repetir um payload malformado só desperdiça tempo.
Persista o ID da tarefa junto com seus próprios registros de trabalho. Se seu processo reiniciar no meio da consulta, você pode continuar consultando em vez de reenviar e pagar por uma geração duplicada.
Imagens de referência e consistência de personagem
Prompts de texto puro funcionam para imagens avulsas, mas falham quando você precisa do mesmo personagem em dez cenários diferentes. Descrever um rosto em palavras e esperar que o modelo o reproduza de forma estável quase nunca funciona — pequenas variações de redação geram pessoas diferentes.
Imagens de referência resolvem esse problema. Você inclui uma ou mais imagens junto com o prompt de texto na requisição, e o modelo as usa como âncoras visuais. A consistência de personagem é o caso de uso central:
- Folha de referência do personagem — uma imagem de referência limpa, vários prompts de cena, mantendo rosto e vestuário consistentes.
- Ancoragem de estilo — a imagem de referência define a linguagem visual, e o prompt orienta o conteúdo.
- Fotos de produto — uma imagem de referência do objeto mantém seu design estável em diferentes fundos.
Na requisição, isso significa preencher o campo de imagens de referência em vez de enviar um valor vazio. Forneça a imagem como URL ou dados codificados, conforme o que a especificação de parâmetros do modelo suportar, e mantenha a referência limpa: um sujeito nítido é melhor que uma cena confusa, porque o modelo capta tudo o que está na imagem, não só a parte que você se importa.
Um padrão prático para o pipeline:
- Gere o personagem uma vez a partir de um prompt de texto detalhado.
- Revise, aceite ou regenere até ficar satisfeito.
- Use essa imagem aprovada como referência para cada cena subsequente.
Esse é o fluxo nano banana API python em resumo: fixe o personagem uma vez e depois altere apenas a parte da cena no prompt. Espere iterar — imagens de referência melhoram a consistência, mas não são perfeitas, então construa a etapa de revisão em vez de supor que toda saída é aproveitável.
Resolução de saída e limitações reais
Resolução é onde suposições causam mais problemas, então trate-a com cuidado.
Tamanho solicitado versus tamanho real
Você pode solicitar um tamanho de saída, mas deve tratá-lo como uma sugestão. O modelo pode retornar dimensões diferentes das solicitadas — especialmente para proporções incomuns. A abordagem robusta é ler as dimensões da imagem que você realmente recebeu e tratá-la de forma genérica: seu armazenamento, miniaturas e layout devem se basear no arquivo real, não no valor solicitado.
O que determina a qualidade
A qualidade da saída é determinada principalmente pelo prompt e, quando usadas, pelas imagens de referência. Um prompt bem composto, com sujeito e iluminação claros, produz uma imagem melhor do que um prompt vago que pede um tamanho maior. Não use resolução para compensar um prompt mal descrito.
Planeje em torno das limitações
- Não codifique dimensões fixas no código downstream. Leia-as da imagem retornada.
- Valide antes de armazenar. Se sua aplicação exige um tamanho mínimo, verifique as dimensões reais após a geração; se forem insuficientes, regenere — não suponha que a requisição já impôs esse requisito.
- Atenção ao tamanho do arquivo. Saídas em resolução maior significam payloads maiores; faça download em streaming ou com buffer, em vez de carregar tudo na memória em um laço.
- Cuidado com processamento em lote. Os limites de concorrência são por conta; se você vai gerar muitas imagens, monte um pequeno pool de workers com retentativas e backoff, em vez de disparar requisições sem limites em um laço.
Para conhecer as capacidades e os valores aceitos do Nano-Banana, consulte a documentação do modelo — não os payloads de exemplo deste artigo. A cobrança segue o modelo normal de uso por consumo da plataforma; consulte o painel de preços para as tarifas atuais, não este tutorial.
Diagnosticando erros comuns
A maioria das falhas de primeira integração se enquadra em algumas categorias. Veja o que verificar em cada uma.
401 / 403 — autenticação
Sua chave está ausente, mal formatada ou não foi enviada. Confirme que o cabeçalho Authorization existe, tem o prefixo Bearer e que a variável de ambiente foi realmente exportada para o shell ou processo que executa o código. Um caractere de nova linha extra no final da chave copiada causa esse problema com mais frequência do que se espera.
400 — payload malformado
Normalmente é uma destas causas: JSON inválido (aspas extras ou vírgula final), Content-Type errado, falta de um campo obrigatório (como prompt ou model), ou campo de imagem de referência enviado em um formato que o modelo não aceita. Imprima o corpo exato que você está enviando e compare campo a campo com a especificação de parâmetros.
404 — caminho ou modelo errado
O caminho do endpoint está errado, ou o identificador do modelo não corresponde a nenhum modelo da plataforma. Copie o nome do modelo literalmente da lista, em vez de digitá-lo de memória.
Timeouts e estagnação de polling
Para chamadas síncronas, um timeout curto demais interrompe trabalhos que poderiam ter sucesso. Para tarefas assíncronas, a estagnação de polling geralmente significa que sua lógica de consulta encerrou cedo demais, ou que a verificação de estado terminal não corresponde à string de status que a API realmente retorna — registre os valores brutos de status e verifique. Mantenha sempre um tempo máximo de espera, para que tarefas travadas falhem de forma ruidosa em vez de pendurar.
Resultado vazio
Retornar 200 sem imagem quase sempre é um problema de conteúdo, não um bug: o prompt pode estar vago demais ou ter sido filtrado. Antes de concluir que há erro na API, verifique os campos de erro ou motivo no corpo da resposta, depois restrinja e esclareça o prompt.
Falhas ao tentar de novo
Se o mesmo payload às vezes funciona e às vezes falha, você provavelmente atingiu um limite de taxa ou encontrou um erro transitório do servidor. Adicione backoff exponencial em torno do envio e da consulta, e não repita um 400 — corrija o payload.
Em caso de dúvida, o diagnóstico mais rápido é fazer uma chamada curl mínima com um prompt simples. Se funcionar, o problema está no seu payload ou no seu código, não nas credenciais.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio