Como usar o Nano-Banana-2-Lite pela API HiAPI: curl, Python e uma requisição funcional

O que é o Nano-Banana-2-Lite e quando usá-lo

O Nano-Banana-2-Lite é a faixa de custo ultrabaixo da família Nano-Banana na HiAPI. Ele se destina a cenários de geração de imagens com alta concorrência e sensíveis a custo, nos quais você valoriza mais despesas previsíveis e iteração rápida do que a máxima fidelidade. Se você está criando o protótipo de um recurso, gerando miniaturas ou variantes em lote, ou executando tarefas em segundo plano que toleram um modelo mais leve, esta faixa é o ponto de partida adequado.

Use-o quando a saída for apenas uma etapa de um pipeline maior: visuais de rascunho, imagens de espaço reservado, experimentos em lote ou testes A/B que exigem muitos candidatos a baixo custo. Para os materiais visuais finais ou cenários que exigem o máximo de detalhe, faça upgrade para uma faixa maior. A interface da API permanece a mesma, portanto você não precisa reescrever a integração para trocar de modelo.

Pré-requisitos e estrutura da requisição

Antes de chamar o Nano-Banana-2-Lite, certifique-se de ter:

• Uma conta HiAPI e uma chave de API. Guarde-a em uma variável de ambiente, por exemplo HIAPI_API_KEY; nunca a envie ao controle de código-fonte.
• Um terminal com curl para o primeiro teste, além de Python 3.8+ e a biblioteca requests para a versão em script.
• Um prompt que descreva a imagem desejada. Comece simples; depois você pode adicionar entradas de referência.

Toda requisição à HiAPI segue a mesma estrutura: um POST com corpo JSON enviado ao endpoint do modelo. O corpo carrega o nome do modelo, o prompt e quaisquer parâmetros opcionais. Como a geração é assíncrona, a chamada de envio retorna um identificador de tarefa, e então você consulta essa tarefa. A resposta é JSON, e os erros incluem um código de status e uma mensagem que você pode registrar.

Seu payload precisa, no mínimo, definir model como nano-banana-2-lite e fornecer um prompt. Campos opcionais como reference_images e configurações de saída são abordados nas próximas seções.

Uma requisição curl funcional

A seguir está um exemplo completo e pronto para copiar e chamar, que envia uma tarefa básica. Substitua o prompt de exemplo pelo seu próprio conteúdo.

curl -X POST https://api.hiapi.ai/v1/images/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1"
  }'

A resposta contém o id da tarefa e um campo status. Tarefas recém-enviadas normalmente retornam queued ou processing. Salve esse id; você o usará na etapa de consulta. Se receber 401, verifique se HIAPI_API_KEY foi exportada no seu shell. Se receber 422, verifique a mensagem de erro para localizar o campo problemático.

Enviar a mesma requisição com Python

Porte a chamada curl para Python, para inseri-la em um script ou serviço. Este exemplo usa requests e lê a chave de uma variável de ambiente.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

Mantenha o corpo da requisição em um dicionário, para estendê-lo com campos opcionais sem reescrever a chamada. Um timeout de 30 segundos é razoável para a etapa de envio, já que o trabalho pesado é feito de forma assíncrona.

Adicionar entradas de referência opcionais

As entradas de referência permitem guiar a geração com contexto visual. Na HiAPI, você as anexa como um array reference_images no mesmo corpo JSON. Cada item é uma URL acessível publicamente ou um data URI base64. Use imagens de referência quando quiser preservar a composição, combinar um estilo ou manter uma foto de produto consistente entre várias variantes.

{
  "model": "nano-banana-2-lite",
  "prompt": "Same layout, but in a warm sunset palette",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

Inclua imagens de referência apenas quando elas fornecerem um sinal útil. Cada referência é um dado extra a transmitir e pode diluir um prompt simples. Para tarefas diretas de texto para imagem, omita o campo por completo. Quando você realmente usar referências, mantenha-as relevantes e em pequena quantidade; uma ou duas imagens bem escolhidas costumam superar um conjunto grande.

Consultar o resultado assíncrono

A geração de imagens é assíncrona: você envia a tarefa e depois consulta o endpoint da tarefa até que o status se torne terminal. O padrão é o mesmo em curl e Python.

Com curl, verifique a tarefa pelo id:

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Em Python, envolva a consulta em um loop com atraso, para não sobrecarregar a API:

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

Comece com um intervalo curto e aumente gradualmente o intervalo se estiver consultando muitas tarefas. Sempre defina um número máximo de tentativas, para que uma tarefa travada não bloqueie seu worker para sempre. Trate failed como estado terminal e registre a mensagem de erro.

Baixar e validar a saída

Quando a tarefa for bem-sucedida, a resposta contém uma ou mais URLs de saída. Busque o arquivo, salve-o localmente e valide o que você recebeu.

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

Faça verificações básicas no conteúdo baixado: confirme que o tipo de conteúdo é imagem, verifique se o tamanho do arquivo é diferente de zero e razoável, e abra-o uma vez para confirmar que corresponde ao seu prompt. Registre o id da tarefa junto com o nome do arquivo local, para rastrear qualquer material até sua requisição.

Checklist de custos e falhas antes de ir para produção

O Nano-Banana-2-Lite tem preço na faixa de custo ultrabaixo; a cobrança segue a medição padrão de geração de imagens da plataforma. Consulte o painel de preços atual no site para obter as tarifas exatas, em vez de codificar suposições.

Antes de lançar, adote estes hábitos:

• Retentativas com backoff. Repita um pequeno número de vezes erros transitórios (timeouts, 5xx) com atraso crescente; não repita erros de validação 4xx.
• Limite as consultas. Use um intervalo fixo e um número máximo de tentativas. Registre o estado final e o tempo decorrido.
• Registre o id da tarefa e o prompt. Armazene o id da tarefa, o prompt, o modelo e quaisquer entradas de referência junto com cada saída, para reproduzir ou auditar execuções.
• Valide as entradas cedo. Antes de enviar, verifique o comprimento do prompt e as URLs de referência, para evitar desperdiçar tarefas.

Com essas verificações, o Nano-Banana-2-Lite é um instrumento de trabalho previsível e de baixo custo para geração em lote e em segundo plano. Explore a página do modelo na HiAPI para obter os parâmetros e detalhes de tarifas mais recentes.