Tutorial
Como usar o nano-banana-2 com a API do HiAPI: exemplos funcionais de curl e Python Requests
Um guia para desenvolvedores sobre como integrar o nano-banana-2 a um pipeline de geração de imagens
Nesta página
O que o nano-banana-2 faz por você e quando usá-lo
O nano-banana-2 é um modelo de geração de imagens acessado via API HTTP. Você envia um prompt, opcionalmente acompanhado de uma imagem de origem, e recebe de volta uma imagem gerada. Esse é todo o modelo mental de que você precisa antes de escrever código.
Use o nano-banana-2 quando precisar gerar imagens programaticamente dentro de um produto ou pipeline existente, em vez de operar por uma janela de chat: criação de materiais de marketing, produção de miniaturas e capas, modificações iterativas a partir de uma imagem base, ou tarefas em lote em que a quantidade de imagens é determinada pelos seus próprios dados. Como a interface dele é uma API comum de requisição/resposta, você pode colocá-lo atrás de um worker de fila, de um endpoint de backend ou de uma ferramenta de CLI, sem introduzir um SDK novo para cada linguagem.
Dois modos cobrem a maioria dos casos de uso:
- Texto para imagem — você descreve o que quer no prompt e recebe a imagem.
- Imagem para imagem — você fornece uma imagem de origem mais um prompt descrevendo a transformação e recebe a imagem modificada.
Os dois modos têm o mesmo formato de requisição, então um único encapsulamento de cliente (que construiremos mais adiante neste artigo) atende a ambos. Se o seu pipeline só renderiza a partir de texto, você pode ignorar completamente o campo image. Se o seu pipeline trata de editar material existente, a entrada é o modo imagem para imagem.
O que o nano-banana-2 não faz por você: ele não gerencia suas repetições, timeouts, armazenamento ou idempotência. Essas são as partes que você constrói em torno da chamada — e é justamente nisso que se concentra a maior parte deste tutorial, porque chamar requests.post de forma ingênua dentro de um loop é a causa mais comum de "a demo funciona, mas em produção não".
Antes de enviar a primeira requisição
Antes da primeira chamada, você precisa de três coisas prontas.
1. Credenciais da plataforma
Você precisa obter acesso à API pela plataforma HiAPI e as credenciais atribuídas à sua conta. Trate-as como segredo: carregue de variáveis de ambiente ou de um gerenciador de segredos, nunca as faça commit em repositório e nunca as cole em artefatos empacotados do cliente. Cada requisição abaixo lê a chave de uma variável de ambiente, então nenhuma informação sensível aparece no código-fonte.
export HIAPI_API_KEY="your-key-here"
2. Ambiente do cliente
Com curl, você só precisa de um shell capaz de executar curl — os exemplos usam argumentos presentes em builds padrão. Com Python, você precisa de Python 3 e da biblioteca requests:
python3 -m venv .venv
source .venv/bin/activate
pip install requests
3. Onde guardar as saídas
A geração de imagens devolve dados de imagem — seja embutidos na resposta, seja como uma referência que pode ser obtida depois, dependendo do formato de resposta devolvido pela sua conta. Decida antecipadamente se vai salvar os bytes em disco, enviá-los para um armazenamento de objetos, ou devolver uma URL ao chamador. Pensar nisso agora evita o clássico momento constrangedor de "funciona no shell, mas não tenho onde colocar o arquivo".
Não é preciso estimar cotas ou preços para começar. O princípio geral para uma primeira integração é: envie a menor requisição válida, confirme que recebe uma resposta válida, e só então adicione parâmetros. É exatamente isso que a próxima seção faz.
Uma requisição curl mínima e funcional
Abaixo está uma chamada completa de texto para imagem. O endpoint, os cabeçalhos e o corpo são as únicas partes variáveis: o endpoint identifica o modelo e a operação na plataforma HiAPI, os cabeçalhos carregam suas credenciais, e o corpo JSON carrega a carga útil.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"prompt": "a minimalist isometric workspace, soft daylight, muted palette",
"n": 1
}'
Defina HIAPI_BASE_URL com o endereço base da API exibido no painel da sua conta HiAPI, para não codificar o hostname diretamente no script. O corpo tem três campos, e os três importam:
modeldiz à plataforma qual modelo executar. Mantenha-o explícito mesmo que use um padrão em outro lugar; isso faz os logs se explicarem por si sós.prompté linguagem natural. Descreva especificamente o sujeito, a composição e o estilo; prompts vagos produzem imagens vagas.né a quantidade de imagens solicitadas para esse prompt. Ao validar se o caminho está funcionando, comece com1.
Uma resposta bem-sucedida devolve os dados da imagem no corpo. Inspecione-a antes de escrever qualquer parser: passe a saída por jq ou redirecione para um arquivo, e então observe as chaves de nível superior. Você está confirmando duas coisas — que a requisição foi aceita, e em que ponto da resposta a carga útil da imagem realmente está.
Não tenha pressa em adicionar parâmetros na primeira chamada. Uma linha de base funcional que você entende vale mais do que um corpo de requisição enorme que você copiou. Depois que essa chamada devolver uma imagem, cada seção seguinte será uma variação dela.
A mesma requisição, escrita em Python
Porte a chamada curl para Python sem alterar a carga útil. Manter uma única fonte de verdade (um dict) significa que o corpo que você validou no shell é o mesmo corpo que vai para produção.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
def generate_image(prompt: str, model: str = "nano-banana-2", n: int = 1,
timeout: float = 60.0) -> dict:
"""Envia uma requisição de texto para imagem e devolve a resposta JSON já analisada."""
payload = {"model": model, "prompt": prompt, "n": n}
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"a minimalist isometric workspace, soft daylight, muted palette"
)
print(result.keys())
Três detalhes merecem destaque, porque são justamente as partes que as pessoas mais esquecem ao copiar trechos de código.
Sempre defina timeout. Sem ele, uma conexão travada bloqueia seu worker indefinidamente. O valor acima é só um ponto de partida, não uma regra rígida — ajuste conforme a latência que você observa na prática.
Use json= em vez de data=. Passar um dict para json define o tipo de conteúdo corretamente e serializa; passar uma string crua para data é exatamente o que causa corpos de requisição malformados que parecem falhas do modelo.
Chame raise_for_status() antes de analisar. Tentar analisar uma resposta 4xx com .json() para extrair campos de imagem gera erros confusos mais adiante. Exponha primeiro o código de status HTTP.
Essa função é o encapsulamento reutilizável mencionado antes. A próxima seção estende a carga útil dela, em vez de substituí-la.
Cargas úteis de texto para imagem e de imagem para imagem
A diferença entre os dois modos é apenas uma: se o corpo da requisição inclui ou não uma imagem de origem. Todo o resto — endpoint, cabeçalho de autenticação, nome do modelo — permanece igual.
Texto para imagem
{
"model": "nano-banana-2",
"prompt": "a minimalist isometric workspace, soft daylight",
"n": 1
}
Imagem para imagem
{
"model": "nano-banana-2",
"prompt": "same scene, but converted to a warm evening palette",
"image": "<base64-encoded source image>",
"n": 1
}
O conceito a internalizar: no modo imagem para imagem, o prompt descreve a transformação, não a cena final do zero. "Converter para uma paleta quente de fim de tarde" funciona melhor do que redescreever a imagem inteira, porque a imagem de origem já fornece o conteúdo.
Duas observações práticas sobre o campo image:
- Codifique a imagem de origem no formato que a documentação da API especifica para esse campo, e mantenha a carga codificada bem abaixo do seu orçamento de tamanho de requisição. Entradas grandes demais são uma das principais causas de rejeição de requisições.
- Se você pretende aceitar uploads de usuários, valide o tamanho e o formato antes de codificar. Falhar rápido do seu lado é muito mais barato do que uma ida e volta que termina em 4xx.
Adicione ao encapsulamento Python um parâmetro opcional image, e uma única função atende aos dois modos:
def generate_image(prompt: str, image: str | None = None, **kwargs) -> dict:
payload = {"model": "nano-banana-2", "prompt": prompt, **kwargs}
if image is not None:
payload["image"] = image
# ... mesma chamada de requisição de antes
Como a ramificação é apenas um if, seu código de chamada decide o modo, e a camada de transporte continua a mesma. Esse é o retorno de manter um único encapsulamento.
Tratando tarefas assíncronas e repetições
A geração de imagens pode demorar mais do que uma chamada típica de API JSON. Algumas respostas devolvem a imagem pronta imediatamente; outras devolvem uma tarefa que você precisa consultar repetidamente até obter o resultado. Mesmo que sua primeira chamada bem-sucedida tenha retornado imediatamente, projete para o cenário de consulta — caso contrário, seu pipeline vai quebrar quando uma geração demorar demais.
Um padrão robusto tem três partes: um laço de consulta com recuo progressivo, um prazo limite rígido, e uma política de repetição que distingue "ainda não está pronto" de "falhou".
import time
import requests
def poll_job(job_id: str, base_url: str, api_key: str,
initial_wait: float = 2.0, max_wait: float = 30.0,
deadline: float = 300.0) -> dict:
start = time.monotonic()
wait = initial_wait
while True:
if time.monotonic() - start > deadline:
raise TimeoutError(f"job {job_id} exceeded deadline")
response = requests.get(
f"{base_url}/v1/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30.0,
)
response.raise_for_status()
body = response.json()
status = body.get("status")
if status == "succeeded":
return body
if status == "failed":
raise RuntimeError(f"job {job_id} failed: {body}")
time.sleep(wait)
wait = min(wait * 2, max_wait)
O caminho da tarefa e o vocabulário de estados devem corresponder ao que a referência da API da sua conta HiAPI especifica — ajuste as chaves acima para o formato correspondente, mas preserve a estrutura.
Regras para mantê-lo saudável em produção:
- Recuo exponencial com teto. Consultar a cada 200 ms desperdiça cota e martela o endpoint; dobrar o tempo de espera com um teto estabiliza em torno do tempo real de conclusão.
- Limite o total de tentativas e o tempo total. O
deadlinenão é negociável. Um laço sem limite é esperar que um dia lento cause uma falha. - Só repita erros repetíveis. Erros de rede transitórios e respostas 5xx merecem nova tentativa com jitter; respostas 4xx não — reenviar uma carga malformada só desperdiça tempo. Use um número pequeno e limitado de tentativas (duas ou três) e registre cada uma.
- Torne as repetições seguras. Se o seu endpoint de criação de tarefas aceita chave de idempotência, envie uma chave estável por requisição lógica, para que reenvios não produzam gerações duplicadas.
Com prazo limite, recuo progressivo e número limitado de tentativas, uma geração lenta passa a ser um evento registrado e tratado, e não um worker travado.
Depurando os erros que você realmente vai encontrar
Quando uma chamada falha, leia primeiro o código de status bruto e o corpo completo da resposta, antes de mexer em qualquer parâmetro do modelo. O corpo da resposta normalmente indica o problema. Adivinhar é mais lento do que registrar logs.
Falha de autenticação
401 ou 403 quase sempre significa uma destas coisas: chave ausente na variável de ambiente, cabeçalho malformado, ou credencial não ativa neste ambiente. Verifique o valor literal do cabeçalho que você está enviando — faltar o prefixo Bearer , ou carregar uma quebra de linha extra vinda de uma chave copiada, são causas comuns.
Erro de carga útil
400 com uma mensagem sobre o corpo da requisição significa que o JSON em si está errado: prompt ausente, vírgula sobrando, uso de data= em vez de json= em Python, ou campo image codificado incorretamente. Imprima uma vez os bytes exatos que você envia, inspecione, e remova a impressão.
Entrada rejeitada
Requisições de imagem para imagem que não passam na validação costumam estar relacionadas à imagem de entrada: grande demais, formato errado ou impossível de decodificar. Valide tamanho e codificação do seu lado antes de enviar, e devolva um erro claro a quem forneceu a imagem, em vez de repetir.
Timeouts e 5xx
Esses pertencem à categoria repetível. Distinga timeouts de conexão de erros do servidor nos logs, e confirme que suas repetições têm limite — caso contrário, um 5xx persistente vira um laço infinito.
Uma sequência de investigação que funciona
- Registre o código de status HTTP e o texto bruto da resposta para cada falha.
- Verifique o caminho das credenciais primeiro, antes de tudo o mais.
- Reenvie a carga que falhou com curl, removendo seu código de cliente da equação.
- Só depois disso ajuste
prompt,imageou outros parâmetros do modelo.
Se a falha persistir depois dos quatro passos, capture o ID de requisição (ou campo de correlação equivalente) da resposta e inclua-o ao contatar o suporte — isso transforma um relato vago em algo rastreável.
Deixando-o pronto para produção
Antes de ir ao ar, passe por esta lista de verificação.
- Segredos: a chave de API é carregada de variável de ambiente ou gerenciador de segredos, e não aparece em logs, mensagens de erro ou artefatos empacotados do cliente.
- Timeouts: toda chamada HTTP — criação, consulta e obtenção da imagem resultante — tem timeout explícito.
- Limites: a consulta tem prazo limite, as repetições têm número máximo de tentativas, e o código distingue falhas repetíveis das não repetíveis.
- Observabilidade: registre, para cada chamada, o formato da requisição (omitido ou com hash se o prompt puder conter dados de usuário), o código de status, a latência e o ID de correlação.
- Consciência de custo: a cobrança segue as dimensões definidas pela sua conta HiAPI, então acompanhe quantas gerações e quantas saídas cada requisição produz, e instrumente seus próprios contadores de uso para que laços descontrolados fiquem visíveis antes da fatura.
- Armazenamento: as imagens geradas vão para um local persistente — armazenamento de objetos ou banco de dados — e não ficam em diretórios temporários que desaparecem junto com o contêiner.
Nenhum desses itens é específico do nano-banana-2. Esse é justamente o ponto: a chamada ao modelo é a parte simples, e tudo em volta é higiene comum de sistemas distribuídos. Construa o encapsulamento uma vez, mantenha a carga útil em um único dict, e texto para imagem e imagem para imagem ficam cobertos de graça.
Comece com a chamada curl, porte-a para o encapsulamento Python, adicione o laço de consulta, e então percorra a lista de verificação. Para detalhes do modelo e a referência de API mais recente, consulte a documentação do nano-banana-2 na plataforma HiAPI.
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