Blogue

Tutorial

Tutorial da API Nano-Banana-2: usando curl e Python Requests funcionais via hiapi

Nov 10, 2026
Arte de capa em vista superior: folhas de papel cor de osso deslocadas em camadas de bordas cor de carvão com uma folha vermelho-ferrugem, 16:9.
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=payload faz o requests serializar o dict para você e definir o Content-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 .env que 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_KEY está realmente exportada no shell ou ambiente que executa a requisição? Execute echo $HIAPI_API_KEY para confirmar.
  • O cabeçalho Authorization está 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.tool e construir o corpo no código em vez de manualmente ajuda.
  • Campos obrigatórios ausentes — model e prompt sã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

  1. Leia literalmente a mensagem de erro e o código de status — eles geralmente apontam o problema.
  2. Reproduza a requisição que falhou no curl com os campos mínimos, depois acrescente complexidade gradualmente.
  3. 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 →

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