Como usar a API Nano Banana 2 Lite: curl, Python e uma requisição executável

O Nano-Banana-2-Lite é a opção econômica da família de modelos de imagem Nano-Banana no hiapi: usa o mesmo workflow baseado em tarefas dos seus irmãos maiores, custa menos por imagem e suporta tanto geração a partir de texto quanto edição com imagem de referência. Este guia percorre um fluxo de integração completo e executável — criar a tarefa, fazer polling, baixar o resultado — demonstrando tanto em curl quanto em Python, e explica as peculiaridades de schema que o diferenciam do Nano-Banana-2 e do Nano-Banana-Pro.

O que você vai construir e o que precisa preparar

Objetivo: enviar um prompt para Nano-Banana-2-Lite, aguardar a geração da imagem e salvá-la em disco.

Você só precisa de uma coisa: uma chave de API do hiapi (sk-...). Obtenha-a no seu painel do hiapi. O custo por imagem está listado na página de preços e na página do modelo Nano Banana 2 Lite.

Todos os modelos de imagem no hiapi rodam por meio de uma API de tarefas assíncronas unificada: você cria a tarefa com POST /v1/tasks e então faz polling em GET /v1/tasks/{id} ou recebe um webhook quando a tarefa for concluída.

Requisição mínima executável (curl)

Criar a tarefa:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana-2-Lite",
    "input": {
      "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
      "aspect_ratio": "3:2"
    }
  }'

O id da tarefa na resposta fica em data.taskId. Faça polling nele:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Quando data.status for "success", a URL da imagem estará em data.output[0].url. Baixe imediatamente — as URLs de saída são assinadas e têm tempo de expiração (expireAt), então salve os bytes, não o link.

Duas regras de schema que costumam pegar as pessoas de surpresa, direto da própria validação da API:

• O id do modelo diferencia maiúsculas de minúsculas. "model": "nano-banana-2-lite" retorna 400 MODEL_UNAVAILABLE ("model not available via /v1/tasks"). Use o id exato Nano-Banana-2-Lite.
• prompt e aspect_ratio são ambos obrigatórios. Omitir qualquer um deles resulta em 400 INVALID_REQUEST com a mensagem missing required field. Valores válidos de aspect_ratio: auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1.

O mesmo fluxo em Python

Sem SDK — a API de tarefas é JSON puro sobre HTTPS:

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Create the task
resp = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json={
        "model": "Nano-Banana-2-Lite",
        "input": {
            "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
            "aspect_ratio": "3:2",
        },
    },
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until the task reaches a terminal state
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(
        f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30
    ).json()["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} did not finish in 10 minutes")

# 3. Download immediately — output URLs are signed and expire
image_url = task["output"][0]["url"]
with open("lighthouse.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved lighthouse.png")

Edição com imagem de referência: é image_urls, não image_input

O Nano-Banana-2-Lite suporta edição de imagem, mas seu campo de imagem de referência é image_urls — um array com até 10 URLs acessíveis publicamente:

{
  "model": "Nano-Banana-2-Lite",
  "input": {
    "prompt": "Replace the background with a clean white studio backdrop, keep the product unchanged",
    "aspect_ratio": "auto",
    "image_urls": ["https://your-cdn.com/product-photo.jpg"]
  }
}

Esta é a armadilha mais comum da família: Nano-Banana-2 e Nano-Banana-Pro usam image_input para o mesmo propósito, enquanto o Lite rejeita esse campo (additional properties 'image_input' not allowed). Nomes de campo como input_urls, images ou reference_images são rejeitados nos três modelos. Se você migrar código entre camadas, normalmente a única alteração necessária é renomear esse campo.

Lite vs. Nano-Banana-2 vs. Pro: diferenças de schema que importam

	Nano-Banana-2-Lite	Nano-Banana-2	Nano-Banana-Pro
Entradas obrigatórias	prompt, aspect_ratio	prompt	prompt
Imagem de referência	image_urls (≤10)	image_input	image_input
Controle de resolution	Não aceito	Aceito	Aceito

O Lite mantém a superfície da interface mínima: prompt, proporção e imagens de referência opcionais. Sem resolution, seed, n ou negative_prompt — enviar qualquer um deles falha na validação com additional properties ... not allowed. Se você precisa de controle explícito de resolução (1K/2K/4K) ou de um nível de fidelidade mais alto, faça upgrade para Nano-Banana-2 ou Nano-Banana-Pro; se você está gerando em lote — thumbnails, rascunhos, loops de iteração, variações em massa — o custo menor por imagem do Lite é justamente o seu propósito.

Reforço para produção

Prefira webhooks ao polling sempre que possível. Adicione um bloco callback ao criar a tarefa e o hiapi fará um POST do resultado final no seu endpoint:

{
  "model": "Nano-Banana-2-Lite",
  "input": { "prompt": "...", "aspect_ratio": "1:1" },
  "callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}

when aceita apenas "final" — você recebe o callback uma única vez, seja em caso de sucesso ou de falha. Polling é adequado para scripts e notebooks; callbacks são melhores para servidores, pois evitam que você gerencie loops de polling e timeouts. Se for mesmo fazer polling, um intervalo de 2–5 segundos com um prazo rígido (como no exemplo em Python) é suficiente.

Trate erros em duas camadas. Falhas no nível da requisição retornam como erros HTTP — uma chave inválida ou não autorizada retorna 401 com {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}, e erros de schema retornam 400 INVALID_REQUEST com a mensagem exata de validação. Falhas no nível da tarefa chegam com status: "fail" e um objeto error na própria tarefa; trate ambos os caminhos no seu código.

Torne as retentativas idempotentes. A criação de tarefas não é idempotente — repetir uma requisição de criação que deu timeout pode gerar duas tarefas (e duas cobranças). Persista o taskId assim que o receber e, após um reinício, continue fazendo polling no id existente em vez de recriar a tarefa cegamente.

Armazene os bytes, não as URLs. As URLs de saída expiram. Antes de fazer qualquer outra coisa com a imagem, baixe-a e coloque-a no seu próprio armazenamento.

Leitura relacionada

• Página do modelo Nano Banana 2 Lite — parâmetros, preço em tempo real, playground
• GPT Image 2 vs Nano Banana 2: comparação lado a lado com o mesmo prompt
• Mantendo a consistência de personagem com Nano-Banana no hiapi
• Documentação do hiapi e preços

FAQ

Por que recebo "model not available via /v1/tasks"? O id do modelo diferencia maiúsculas de minúsculas. Use exatamente Nano-Banana-2-Lite; a variante em minúsculas é rejeitada com 400 MODEL_UNAVAILABLE.

O Nano-Banana-2-Lite suporta edição imagem-para-imagem? Sim. Passe a imagem de referência no array image_urls (até 10 URLs). Ele consegue lidar com substituição de fundo, transferência de estilo e workflows de edição guiados por instruções a partir do prompt.

Por que meu código do Nano-Banana-2 falha no Lite com "additional properties 'image_input' not allowed"? Camadas diferentes usam nomes de campo de imagem de referência diferentes: o Lite espera image_urls, enquanto Nano-Banana-2 e Pro esperam image_input. Renomeie o campo ao alternar entre camadas.

Posso definir resolution, seed ou quantidade de imagens? No Lite, não — o schema de entrada dele aceita apenas prompt, aspect_ratio e image_urls. Para controle de resolution em 1K/2K/4K, use Nano-Banana-2 ou Nano-Banana-Pro.

Quanto tempo as URLs das imagens de saída permanecem válidas? São URLs assinadas com um timestamp de expiração (expireAt no objeto de saída). Baixe os bytes imediatamente e armazene no seu próprio storage; nunca faça hotlink da saída de uma tarefa.

O que significa 401 permission_denied? Sua chave de API é inválida ou não tem permissão para usar este modelo. Verifique a chave no seu painel e certifique-se de enviá-la no formato Authorization: Bearer sk-....

Quanto custa o Nano-Banana-2-Lite por imagem? Cobrança por uso, por imagem, posicionado como o nível mais barato da família Nano-Banana. Consulte as tarifas atuais na página de preços.