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

TL;DR

• O que é: Versão mais recente da série Nano Banana, do Google, com geração de texto para imagem e edição com imagem de referência usando o mesmo ID de modelo. Já está disponível na HiAPI: abra a página do modelo e insira um prompt para gerar; novos usuários ganham 200 créditos ao se registrar, o suficiente para cerca de 4 imagens em 1K.
• Quanto custa: Cobrança por imagem, 1K $0.022, 2K $0.036, 4K $0.058, cerca de 33%–39% mais barato que o Nano Banana 2, sem acréscimo por imagem de referência.
• Como chamar a API: POST https://api.hiapi.ai/v1/tasks, com model definido como gemini-nano-banana-2.1; após obter o taskId, consulte ou aguarde o callback e baixe data.output[0].url.

No recém-lançado Nano Banana 2.1, as duas perguntas mais frequentes são: o que ele faz e em quanto tempo consigo integrá-lo ao meu projeto. A primeira resposta está nos 5 pontos abaixo; a segunda leva apenas 5 minutos.

O que o Nano Banana 2.1 faz?

• De 30% a 40% mais barato que o NB 2. Cerca de 33%–39% mais barato por imagem na mesma resolução; em 1K custa apenas $0.022, e a sintaxe dos parâmetros é igual à do NB 2.
• Aceita 10 imagens de referência de uma vez. Modelo, roupa, cenário e imagem do produto enviados juntos e fundidos em uma só imagem, ideal para troca de figurino e propostas de identidade visual de marca.
• 15 proporções, incluindo até 1:8 e 8:1. Além das comuns 1:1, 4:5, 16:9 e 21:9, também gera imagens alongadas como 1:4, 4:1, 1:8 e 8:1, criando imagens longas de página de detalhes e banners de uma só vez.
• Três resoluções: 1K, 2K e 4K. 1K para testar prompts, 2K e 4K para gerar a arte final.
• Texto para imagem e edição usam o mesmo ID de modelo. Apenas com o prompt, é geração de texto para imagem; adicionando uma imagem de referência, vira edição, sem precisar de dois conjuntos de código.

Ensaio de moda do Nano Banana 2.1, 2K / 16:9, saída 2752×1536.

Gerar com este prompt →

Dois caminhos: testar online ou usar a API?

Para ver o resultado primeiro, escolha o teste online; para integrar ao produto, escolha a API. Os dois caminhos usam o mesmo modelo e a mesma tabela de preços.

Teste online (cerca de 1 minuto)

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

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

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

1K custa $0.022 por imagem; com $10 é possível gerar cerca de 450 imagens, o suficiente para ajustar o prompt até ficar satisfatório. Consulte todos os parâmetros na documentação em chinês.

Primeira imagem: versão 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": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "A fashion editorial photograph of a model in an ivory linen blazer on a sunlit white-stucco terrace above the Mediterranean, 50mm lens, soft directional light, cinematic color grade",
      "aspect_ratio": "4:5",
      "resolution": "2K",
      "output_format": "png"
    }
  }'

O ID da tarefa retornada fica em data.taskId:

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

Consultar o resultado:

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

Apenas prompt é obrigatório. aspect_ratio tem padrão auto, resolution tem padrão 1K e output_format pode ser jpg ou png.

Primeira imagem: versão Python

Criação, polling e download em um único bloco; basta copiar e trocar pela sua Key para executar:

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "gemini-nano-banana-2.1",
    "input": {
        "prompt": "A fashion editorial photograph of a model in an ivory linen blazer on a sunlit white-stucco terrace above the Mediterranean, 50mm lens, soft directional light, cinematic color grade",
        "aspect_ratio": "4:5",
        "resolution": "2K",
        "output_format": "png",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    status = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if status["status"] in ("success", "fail"):
        break
    time.sleep(2)

if status["status"] == "success":
    image_url = status["output"][0]["url"]
    with open("nano-banana-2-1.png", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(status.get("error"))

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

Adicione image_input dentro de input e a mesma requisição vira edição. Abaixo usamos diretamente o ensaio de moda acima como imagem de referência, alterando apenas a cor do blazer:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "Change the model'\''s blazer to deep burgundy silk while keeping her pose, the terrace, and the lighting unchanged",
      "image_input": ["https://static.hiapi.ai/model-examples/gemini-nano-banana-2.1/2026/10/08/1791466473082-3e77d5c2a1ef0ef6-coastal-fashion-2k.webp"],
      "resolution": "2K"
    }
  }'

image_input aceita até 10 URLs públicas, nos formatos JPEG, PNG e WebP, com no máximo 30MB por imagem. No prompt, escreva separadamente "o que alterar" e "o que preservar"; quanto mais específicos os itens a preservar, mais estável fica a imagem original.

3 pontos de atenção antes de ir para produção

1. Use callback no servidor. Adicione "callback": {"url": "https://yourapp.com/webhook", "when": "final"} no corpo da requisição para ser notificado automaticamente ao fim da tarefa, dispensando o polling.
2. Em caso de timeout, não repita o POST. Cada POST /v1/tasks cria uma nova tarefa e é cobrado separadamente. Salve o taskId e faça deduplicação no seu próprio sistema antes de tentar novamente.
3. Defina resolution explicitamente em cada requisição. A resolução determina diretamente o preço unitário; fixe-a na requisição para ter uma fatura previsível.

Erros comuns, um por linha

• 400 additional properties '<field>' not allowed → Nome de campo com erro de digitação ou campo de outro modelo (como image_urls) → Confira a documentação e use o nome correto, como image_input.
• 400, aviso de valor inválido em aspect_ratio → Foi enviada uma proporção fora da lista → Escolha um dos 15 valores válidos listados no erro.
• 401 permission_denied → Key ausente, incorreta ou revogada → Verifique o cabeçalho Authorization: Bearer sk-... e, se necessário, recrie a Key no console.
• Criação bem-sucedida, mas tarefa em fail / INVALID_REQUEST → A URL da imagem de referência não abre ou não é uma imagem → Troque por um JPEG, PNG ou WebP acessível publicamente.
• O link da imagem deixa de abrir após alguns dias → O link de saída tem validade → Baixe imediatamente após receber o resultado e armazene o arquivo em si.

O valor pré-cobrado de tarefas com falha é reembolsado integralmente de forma automática.

Perguntas frequentes

O Nano Banana 2.1 pode substituir diretamente o NB 2? Sim. Os nomes dos parâmetros são idênticos; basta alterar model para gemini-nano-banana-2.1 para trocar, com cerca de 33%–39% de economia por imagem na mesma resolução. Único ponto de atenção: o 2.1 gera JPG por padrão; se precisar de PNG, escreva explicitamente "output_format": "png".

As imagens de referência têm custo adicional? Não. O preço depende apenas da resolução de saída; enviar 1 ou 10 imagens de referência custa o mesmo.

É possível gerar com fundo transparente? Os formatos de saída são jpg ou png; para material com fundo transparente, escolha o GPT Image 2.5, que em 1K oferece suporte a background: transparent.

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

Série de artigos sobre o Nano Banana 2.1

• Página do modelo Nano Banana 2.1: geração online, 200 créditos de bônus no cadastro
• Quanto custa a API do Nano Banana 2.1: preços unitários 1K/2K/4K e orçamento mensal
• Nano Banana 2.1 vs GPT Image 2.5: como escolher por orçamento e cenário
• Coleção de prompts do Nano Banana 2.1: 5 cenários para copiar e gerar direto
• Documentação de integração em chinês do Nano Banana 2.1: todos os parâmetros e códigos de erro

Experimente agora: clique em Gerar com este prompt → abaixo do ensaio de moda acima: o prompt já está preenchido, basta escolher 2K e 16:9 e clicar uma vez para obter o mesmo resultado.