Tutorial
Tutorial da API Nano-Banana-2: usando curl e Python Requests funcionais via hiapi
Nesta página
Preparação antes da primeira chamada
Antes de enviar qualquer requisição ao Nano-Banana-2, prepare quatro coisas. Nenhuma delas leva muito tempo, e com todas prontas, a primeira requisição se torna um exercício de copiar e colar em vez de uma caça ao tesouro.
1. Conta hiapi e chave de API
Toda requisição é autenticada por uma chave de API vinculada à sua conta hiapi. Crie a chave no painel da conta e guarde-a em um local seguro — um gerenciador de senhas ou uma variável de ambiente na sua máquina. Trate-a como uma senha: nunca a envie para um repositório de código nem a cole em documentos compartilhados.
Na sua máquina, exporte-a uma vez por sessão de shell, para que os exemplos abaixo possam lê-la sem nada codificado diretamente:
export HIAPI_API_KEY="your_api_key_here"
2. URL base da API
A URL base é o endereço raiz sobre o qual todas as requisições são construídas. Ao construir um endpoint, você acrescenta a rota do modelo a ela. Coloque a URL base em uma variável de configuração no código, em vez de espalhá-la por vários arquivos — assim, se ela mudar, você altera apenas uma linha.
3. Cliente para enviar requisições
Para começar, você só precisa de um dos seguintes:
- curl — quase certamente já instalado. Use-o para confirmar que sua chave e o corpo da requisição estão corretos antes de escrever qualquer código de aplicação.
- Python 3 com a biblioteca
requests(pip install requests). A maioria dos leitores usará isto para construir integrações reais.
Ter ambos é útil: o curl isola a requisição do seu código, então se algo der errado, você saberá se o problema está na chamada da API ou na aplicação.
4. Saber claramente o que você quer gerar
O Nano-Banana-2 suporta tanto texto-para-imagem quanto imagem-para-imagem. Decida antecipadamente qual modo você precisa, pois a estrutura do corpo da requisição é diferente (detalhado mais adiante). Na primeira chamada, comece com texto-para-imagem — é o que tem menos variáveis.
Com a chave exportada, o cliente instalado e o prompt pensado, agora podemos examinar a requisição em si.
Componentes de uma requisição ao Nano-Banana-2
Uma chamada ao Nano-Banana-2 é uma requisição POST com corpo JSON. Cada campo tem sua função, e entendê-los separadamente significa que, quando algo der errado, você pode alterar uma coisa de cada vez.
Endpoint
A requisição é enviada para a URL base da API hiapi, com a rota do modelo Nano-Banana-2 acrescentada. O método é sempre POST, porque você está enviando um payload a ser processado, e não obtendo um recurso.
Cabeçalhos da requisição
Dois cabeçalhos são importantes:
Content-Type: application/json— informa à API como interpretar seu corpo de requisição.Authorization— carrega sua chave de API. Os exemplos abaixo a leem da variável de ambiente que você exportou anteriormente.
Se qualquer um dos cabeçalhos estiver ausente ou mal formatado, a requisição falhará antes mesmo de o modelo vê-la. Esta é a fonte única mais comum de erros confusos.
Campos do corpo da requisição
Uma requisição texto-para-imagem carrega os seguintes campos:
model— especifica que o modelo a executar é o Nano-Banana-2. Mesmo que exista um valor padrão, declare-o explicitamente; isso torna seu código autoexplicativo e protege você caso o padrão mude.prompt— descreve em linguagem natural a imagem que você deseja. É aqui que ocorre a maior parte do seu trabalho de iteração. Seja específico: sujeito, composição, estilo, iluminação. Prompts vagos geram resultados vagos.- Entrada de imagem — ausente ou vazia no modo texto-para-imagem. No modo imagem-para-imagem, carrega sua imagem de referência (mais detalhes na seção de imagem-para-imagem).
- Parâmetros de saída e dimensões — campos específicos do modelo que afetam a forma ou proporção do resultado retornado. Defina apenas os campos que a documentação do modelo indica como suportados; em APIs estritas, campos desconhecidos geralmente significam requisição rejeitada, e não ignorada silenciosamente.
O que é retornado
A resposta é JSON. Dependendo de como a chamada é construída, você receberá diretamente os dados da imagem gerada ou uma referência a ela. Seu código cliente deve verificar primeiro o status HTTP e só depois examinar o corpo da resposta — não presuma que uma resposta com aparência de 200 contenha necessariamente uma imagem sem verificar.
A estrutura completa é esta: uma requisição POST autenticada com um pequeno corpo JSON explícito. Todo o restante deste tutorial são apenas variações dessa forma.
Uma requisição curl funcional
Esta é a menor chamada completa que você pode enviar. Execute-a em um terminal onde a chave de API já foi exportada, e em poucos segundos você saberá se a conta, a chave e o caminho de rede estão todos funcionando.
curl -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition"
}'
Defina a URL base uma vez no shell, junto com a chave:
export HIAPI_BASE_URL="https://api.hiapi.ai"
(Use a URL base exibida no seu painel hiapi — esse é o valor autoritativo para sua conta.)
Lendo a saída
O curl imprime a resposta bruta no stdout. Se a chamada for bem-sucedida, você verá um JSON contendo a imagem gerada. Faça o pipe por python -m json.tool para formatar a saída e confirmar a estrutura:
curl -s -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{"model":"nano-banana-2","prompt":"a red fox in fresh snow, side profile, crisp detail"}' \
| python -m json.tool
Interpretando o que você vê
- Resposta bem-sucedida — confirma que sua chave é válida, o endpoint está correto e o corpo da requisição pôde ser interpretado. Salve este comando funcional — é sua linha de base.
- Resposta de erro — indica que algo está errado nos três cabeçalhos ou no corpo da requisição. Copie o texto do erro; a seção de depuração mapeia erros comuns para as correções.
O valor de começar com curl está no isolamento. Sua chave, cabeçalhos e JSON estão todos visíveis em um só lugar, então uma falha aponta para a própria requisição, e não para o código da sua aplicação. Uma vez que este comando funcione, portá-lo para Python é um trabalho mecânico.
A mesma requisição em Python
Abaixo está a mesma chamada implementada com requests. O corpo da requisição é o mesmo dict que você viu no corpo do curl — nada muda na API em si, apenas a forma como você a envia.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
payload = {
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition",
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
response = requests.post(
f"{BASE_URL}/nano-banana-2",
json=payload,
headers=headers,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Por que está escrito assim
json=payloadfaz orequestsserializar o dict para você e definir oContent-Type. Você ainda pode passar esse cabeçalho explicitamente; não faz mal e torna a requisição autoexplicativa.timeout=120— a geração de imagem não é instantânea. Um timeout generoso evita que o cliente desista enquanto o modelo ainda está trabalhando. Ajuste esse valor de acordo com seu caso de uso.raise_for_status()converte respostas não 2xx em exceções, de modo que falhas aparecem imediatamente em vez de fluírem silenciosamente para o código de tratamento de resultados.- Variáveis de ambiente mantêm a chave longe do código-fonte. Em produção, injete-a a partir do armazenamento de segredos da plataforma, em vez de usar um arquivo
.envque pode ser commitado.
Extraindo a imagem
O corpo da resposta é JSON. Inspecione-o interativamente uma vez para entender a estrutura exata, depois extraia o campo da imagem explicitamente:
image_url = data["image_url"] # confirme o nome da chave em uma resposta real
Se sua resposta trouxer dados base64 em vez de uma URL, decodifique e grave:
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(data["image_base64"]))
Não adivinhe os nomes dos campos — imprima a resposta bruta na primeira chamada bem-sucedida e use o que realmente estiver presente. Esse único hábito evita a maioria dos defeitos de integração.
Texto-para-imagem vs. imagem-para-imagem com imagem de referência
Até aqui foi texto-para-imagem: você fornece um prompt e recebe uma imagem. O Nano-Banana-2 também suporta imagem-para-imagem, em que você fornece uma imagem de referência que o modelo usa como orientação. Saber quando alternar entre os modos e como o corpo da requisição muda é a diferença entre uma chamada bem-sucedida e uma rejeitada.
Quando usar cada modo
- Texto-para-imagem — você tem uma ideia expressa em texto e nenhuma imagem inicial. Ideal para exploração, ilustração e qualquer conteúdo gerado do zero.
- Imagem-para-imagem — você tem uma imagem existente e quer uma variação, uma reestilização ou uma edição que preserve sua estrutura ou sujeito. É o modo para iteração de design, correspondência de estilo visual ou transformação de fotos.
Se seu prompt é “faça parecer com...” ou “mantenha o layout mas...”, então você precisa de imagem-para-imagem.
Como a imagem de referência altera a requisição
O endpoint e os cabeçalhos permanecem os mesmos. O que muda é o corpo da requisição: você adiciona um campo de imagem de referência ao lado do prompt. Dependendo de como a imagem é fornecida, esse campo carrega uma URL ou dados de imagem codificados. Lembre-se destas regras:
- Se passar um link, use uma URL diretamente acessível ao público. Páginas que exigem login ou redirecionam por autenticação falharão — a API precisa obter os bytes diretamente.
- Use o formato esperado. Formatos comuns como PNG e JPEG são seguros; arquivos incomuns ou corrompidos são uma causa frequente de requisições rejeitadas.
- Verifique os limites de tamanho antes de enviar. Imagens grandes são frequentemente causa de erros no corpo da requisição.
- Mantenha o prompt focado. Com uma imagem de referência, descreva a transformação desejada, não a imagem de referência novamente.
Um corpo de requisição imagem-para-imagem ilustrativo é assim:
payload = {
"model": "nano-banana-2",
"prompt": "Same subject, restyled as a graphite sketch with light crosshatching",
"image_url": "https://example.com/your-reference.jpg",
}
Como sempre, confirme os nomes exatos dos campos com sua primeira resposta bem-sucedida. O princípio é simples: texto-para-imagem tem apenas o prompt; imagem-para-imagem adiciona uma imagem de referência validada à mesma forma de requisição. Primeiro prove que o fluxo funciona com texto-para-imagem, depois acrescente a imagem de referência.
Tratando erros e depurando requisições com falha
Falhas em chamadas ao Nano-Banana-2 se resumem a três categorias. Aprenda a identificar cada uma e você corrigirá a maioria dos problemas em menos de um minuto.
Erros de autenticação
Se você vê um erro de autenticação, a chave não chegou corretamente à API. Verifique em ordem:
- A
HIAPI_API_KEYestá realmente exportada no shell ou ambiente que executa a requisição? Executeecho $HIAPI_API_KEYpara confirmar. - O cabeçalho
Authorizationestá presente e bem formatado? Tanto o esquema quanto a chave importam. - A chave foi revogada ou rotacionada no painel?
- Você está acessando a URL base correta da sua conta?
401 ou 403 quase sempre significam uma dessas quatro situações. A chave em si raramente é o problema — o encanamento em torno dela é que costuma ser.
Corpo da requisição malformado
Erros da classe 400 normalmente significam que a API não conseguiu interpretar ou validar seu corpo de requisição:
- JSON inválido — vírgulas sobrando, aspas simples em vez de duplas, ou caracteres não escapados. Fazer o pipe da saída do curl para
python -m json.toole construir o corpo no código em vez de manualmente ajuda. - Campos obrigatórios ausentes —
modelepromptsão os mais esquecidos; envie ambos explicitamente sempre. - Campos desconhecidos ou não suportados — APIs estritas rejeitam campos que não reconhecem. Remova todo excesso até a requisição passar, depois acrescente um item de cada vez.
- Tipos de valor errados — números enviados como strings, ou arrays onde se espera um único valor. Corresponda exatamente aos tipos da documentação.
Entrada de imagem ruim
Relevante apenas para imagem-para-imagem, mas a mais frustrante quando acontece: URLs de imagem que exigem autenticação, URLs atrás de redirecionamentos, URLs que retornam HTML em vez de imagem, tamanho excessivo ou formato não suportado. Confirme que a URL carrega diretamente no navegador sem login e verifique tipo e tamanho do arquivo em relação aos limites antes de enviar.
Uma sequência de depuração eficaz
- Leia literalmente a mensagem de erro e o código de status — eles geralmente apontam o problema.
- Reproduza a requisição que falhou no curl com os campos mínimos, depois acrescente complexidade gradualmente.
- Imprima o corpo completo da resposta antes de processá-lo; não confie nas suposições sobre sua estrutura.
Se a chamada curl mínima funciona e sua aplicação falha, o defeito está no seu código, não na API. Essa é a fronteira de diagnóstico mais rápida que você pode traçar.
Integrando à sua aplicação
Uma requisição funcional é um bom começo; uma integração confiável precisa de um pouco mais em volta. Veja como passar de uma chamada pontual para algo em que você pode confiar.
Encapsule a chamada em uma função
Isole a requisição em uma função que recebe o prompt (opcionalmente uma imagem de referência) e retorna o resultado. Coloque cabeçalhos, URL base e construção do corpo dentro dessa função, para que o restante da base de código nunca os toque. Quando a API mudar, você editará apenas um lugar.
Trate retentativas com intenção
A geração pode falhar temporariamente por motivos alheios ao seu corpo de requisição. Use retentativas com backoff exponencial, mas apenas para falhas retentáveis — timeouts e certos erros do lado do servidor. Nunca retente erros de autenticação ou de validação do corpo da requisição; eles falharão da mesma forma todas as vezes e só aumentarão a carga. Limite o número de tentativas para que problemas persistentes se revelem em vez de ficar pendurados.
Timeouts e concorrência
Defina um timeout generoso o suficiente para a geração, mas com limite superior, e ajuste-o após medir os tempos reais de resposta. Se você vai emitir muitas requisições, respeite limites razoáveis de concorrência em vez de disparar tudo de uma vez — uma fila com pool de workers é mais previsível do que chamadas paralelas ilimitadas.
Armazene o que você gera
A resposta entrega a imagem gerada. Copie-a prontamente para seu próprio armazenamento, em vez de depender da URL retornada permanecer válida indefinidamente. Nomeie arquivos de forma determinística e registre o prompt e os parâmetros ao lado de cada saída — você precisará dessa proveniência ao iterar prompts mais tarde.
Mantenha a chave fora do código
Leia a chave de API de variáveis de ambiente ou de um gerenciador de segredos em cada ambiente. Rotacione a chave periodicamente. Se ela aparecer onde não deveria, revogue-a no painel.
Comece pequeno, depois expanda
Faça um prompt funcionar no curl, porte para Python, adicione o tratamento de erros da seção anterior e só então construa a fila e o armazenamento ao redor. Cada passo comprova o anterior.
Com uma chamada curl validada, um cliente Python equivalente e as três categorias de erro tratadas, você tem o caminho completo da primeira requisição à integração em produção.
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