Como usar a API do Nano Banana 2? Gere sua primeira imagem em 5 minutos

TL;DR

• O que é: Nano Banana 2, do Google, usa o mesmo ID de modelo nano-banana-2 para geração de imagem a partir de texto e edição com imagem de referência, com até 14 imagens de referência por vez. Já está disponível na HiAPI: abra a página do modelo, insira o prompt e gere; novos usuários ganham 200 créditos ao se cadastrar.
• Quanto custa: cobrança por imagem, 1K $0.036, 2K $0.057, 4K $0.086, imagens de referência sem acréscimo, reembolso automático em caso de falha.
• Como chamar a API: POST https://api.hiapi.ai/v1/tasks, coloque nano-banana-2 em model, obtenha o taskId e consulte ou aguarde o callback, depois baixe de data.output[0].url.

O que o Nano Banana 2 pode fazer?

• Um modelo, dois usos. Só com prompt é geração de imagem a partir de texto; adicionando image_input vira edição com imagem de referência, sem trocar de endpoint ou modo.
• Até 14 imagens de referência por vez. Envie imagens de produto em vários ângulos, fotos de modelo e imagens de cenário juntas; ideal para trocar cenário mantendo o mesmo produto, trocar roupas e criar conjuntos de imagens de marca.
• 14 proporções fixas mais auto. Além das comuns 1:1, 4:5, 16:9 e 21:9, há também 1:4, 4:1, 1:8 e 8:1; em caso de dúvida, use o padrão auto.
• Três níveis: 1K, 2K e 4K. Use 1K para testar prompts, 2K e 4K para o resultado final; saída padrão em PNG.

A imagem abaixo é um exemplo da página do modelo Nano Banana 2, gerada em 4:3 e 1K:

A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography, 4:3

Gerar com este prompt →

Duas formas de começar: teste online ou API?

Para ver o resultado primeiro, teste online; para integrar no produto, use a API. As duas formas usam o mesmo modelo e os mesmos preços.

Teste online (cerca de 1 minuto)

1. Abra a página do modelo Nano Banana 2, ou clique diretamente no link abaixo da imagem acima, e o prompt será preenchido automaticamente.
2. Cadastre-se ou faça login; novas contas já vêm com 200 créditos.
3. Escolha a proporção e a resolução; no preço normal, uma imagem 1K custa 72 créditos.
4. Clique em gerar e baixe se gostar do resultado.

Integração via API (cerca de 5 minutos)

1. Crie uma API Key no console da HiAPI (sk-...).
2. Faça POST /v1/tasks para criar a tarefa e obtenha data.taskId na resposta.
3. Consulte com GET /v1/tasks/{id}, ou inclua callback.url no corpo da requisição e aguarde a notificação.
4. Quando data.status virar success, baixe a imagem de data.output[0].url.

Uma imagem 1K custa $0.036; com $10 dá para gerar cerca de 277 imagens, o suficiente para ajustar bem os prompts. Consulte todos os parâmetros na documentação em chinês.

Primeira imagem: versão curl

Criar a tarefa:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "output_format": "png"
    }
  }'

O ID da tarefa retornada fica em data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Consultar o resultado:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

O único campo obrigatório é prompt. aspect_ratio usa auto por padrão, resolution usa 1K por padrão, output_format usa png por padrão (ou jpg).

Primeira imagem: versão Python

Primeiro instale requests (python3 -m pip install requests) e defina HIAPI_API_KEY no terminal (export HIAPI_API_KEY="sk-YOUR_KEY"). O exemplo abaixo cria a tarefa, faz polling por até 10 minutos e baixa a imagem; se der timeout, guarde o taskId e continue consultando:

import os
import time
import uuid
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
HEADERS["Idempotency-Key"] = str(uuid.uuid4())  # Save with this business task before submitting.

payload = {
    "model": "nano-banana-2",
    "input": {
        "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
        "aspect_ratio": "4:3",
        "resolution": "1K",
        "output_format": "png",
    },
}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


task_id = task_data(requests.post(API, headers=HEADERS, json=payload, timeout=30))["taskId"]
print(f"taskId: {task_id}", flush=True)  # Save this ID for later queries.

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    task = task_data(requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30))
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        with open("nano-banana-2.png", "wb") as f:
            f.write(image.content)
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task {task_id} failed: {task}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")

Edição com imagem de referência: basta adicionar image_input

Adicione image_input dentro de input e a mesma requisição vira edição. O exemplo abaixo coloca uma foto de produto de frasco de sérum em fundo branco sobre uma bancada de banheiro:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "Place this exact serum bottle, unchanged, on a white marble bathroom counter next to a folded beige linen towel, soft warm morning window light",
      "image_input": ["https://static.hiapi.ai/blog/nano-banana-ecommerce-product-images-hiapi/shot-1-listing.jpg"],
      "aspect_ratio": "4:3",
      "resolution": "1K"
    }
  }'

image_input é um array de URLs, com no máximo 14 imagens, e devem ser links de imagens acessíveis diretamente pela internet pública; SVG não é suportado. Escreva claramente no prompt "o que manter" (this exact serum bottle, unchanged) para que o rótulo do produto e o formato do frasco fiquem mais estáveis. Os prompts completos e as imagens geradas desse conjunto de troca de cenário mantendo o mesmo produto estão em Guia completo de prompts do Nano Banana 2.

3 coisas para observar antes de ir para produção

1. Use callback no servidor. Adicione no nível superior do corpo da requisição "callback": {"url": "https://yourapp.com/webhook", "when": "final"} para ser notificado automaticamente ao fim da tarefa; tanto sucesso quanto falha geram callback, então deduplique por taskId.
2. Use chave de idempotência nas retentativas. Cada POST /v1/tasks cria uma nova tarefa e cobra separadamente por padrão. Adicione o cabeçalho Idempotency-Key, gere e salve uma chave para a mesma tarefa de negócio; em caso de timeout de rede, repita com a mesma conta, a mesma chave e exatamente o mesmo corpo de requisição, e a tarefa será criada apenas uma vez.
3. Baixe o resultado assim que recebê-lo. Os links de saída têm prazo de validade; salve a imagem no seu próprio armazenamento antes de qualquer processamento posterior.

Erros comuns, um por linha

• 400 additional properties ... not allowed → nome de campo digitado errado, ou campo de outro modelo usado (como image_urls do Nano Banana 2 Lite, ou size) → altere para image_input e resolution.
• 400, valor de aspect_ratio inválido → proporção fora da lista enviada → escolha um dos 15 valores válidos.
• 401 permission_denied → Key ausente, incorreta ou revogada → verifique o cabeçalho Authorization: Bearer sk-... e, se necessário, recrie no console.
• 402 → saldo insuficiente, a tarefa não foi criada e não houve cobrança → recarregue e tente novamente.
• Tarefa com status igual a fail → ajuste a requisição conforme o error retornado, não repita igual; o valor pré-cobrado é reembolsado integralmente de forma automática.

Perguntas frequentes

Como escrever o ID do modelo? Use nano-banana-2. Os nomes de parâmetros são exatamente os mesmos do Nano Banana 2.1; basta trocar para gemini-nano-banana-2.1 para usar a 2.1.

As imagens de referência têm custo extra? Não. O preço depende apenas da resolução de saída; enviar 1 ou 14 imagens de referência é igual.

Quantas imagens por vez? Uma tarefa gera uma imagem. Para várias, crie várias tarefas em paralelo, com cobrança por imagem.

Como obter o preço promocional por tempo limitado? Sem alterar o código. O desconto de 50% do Dia do Programador vai até 2026-11-09 00:00 no horário de Pequim; a API e o teste online aplicam automaticamente 50% de desconto, ficando $0.018 por imagem 1K.

Artigos da série Nano Banana 2

• Página do modelo Nano Banana 2: geração online, cadastro com 200 créditos
• Quanto custa a API do Nano Banana 2: preço unitário 1K/2K/4K e orçamento mensal
• GPT Image 2.5 vs Nano Banana 2: comparação de 9 imagens com o mesmo prompt
• Guia completo de prompts do Nano Banana 2: 5 cenários para copiar e gerar
• Preço da API do Nano Banana 2.1: quanto mais barato que o NB 2
• Preço da API do Nano Banana Pro: quanto custa por imagem
• Documentação de integração em chinês do Nano Banana 2: todos os parâmetros

Teste agora: clique no link Gerar com este prompt → abaixo da imagem da floresta tropical acima; o prompt já está preenchido, escolha proporção 4:3 e resolução 1K, execute e baixe o resultado, por $0.036 por imagem no preço normal.