Blogue

Tutorial

Como usar o Nano-Banana pela API do HiAPI: curl, Python e requisições executáveis

Nov 12, 2026
Planos de vidro translúcido sobrepostos e abstratos, que refratam o fundo cinza-claro em faixas de azul frio, usados como imagem de capa do tutorial
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:

  1. Enviar uma requisição de geração com o prompt e quaisquer entradas opcionais.
  2. Aguardar a conclusão da tarefa gerada, porque a geração de imagens leva mais tempo do que uma simples conclusão de texto.
  3. 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 ser application/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

  1. Sempre limite o tempo total de espera. Trabalhos que nunca terminam não podem travar seu processo de trabalho. O max_wait acima é sua via de saída.
  2. 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.
  3. Verifique o estado terminal. succeeded significa que você pode ler a saída; failed significa 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:

  1. Gere o personagem uma vez a partir de um prompt de texto detalhado.
  2. Revise, aceite ou regenere até ficar satisfeito.
  3. 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 →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API