Guia de uso

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

4 passos no teste online, 4 passos na integração via API, com curl e Python prontos para executar, exemplos de edição com imagem de referência e guia rápido de erros comuns.

Oct 12, 2026

TL;DR

O que é: Gemini 3 Pro Image, do Google, a linha de topo da série Nano Banana; geração de imagem a partir de texto e edição com imagem de referência usam o mesmo ID de modelo nano-banana-pro. Já está disponível na HiAPI — abra a página do modelo, insira o prompt e gere; novos usuários ganham 200 créditos no cadastro, o suficiente para 1 imagem 2K no preço normal.
Quanto custa: cobrança por imagem, 1K e 2K têm o mesmo preço de $0.057, 4K custa $0.1, calculado por imagem gerada, cerca de 57%–58% mais barato que o preço padrão oficial do Google, sem acréscimo por imagem de referência.
Como chamar a API: POST https://api.hiapi.ai/v1/tasks, coloque nano-banana-pro em model, receba o taskId e depois consulte ou aguarde o callback, e baixe data.output[0].url.

Os custos de tokens de entrada do Google são cobrados à parte; a comparação de preços acima é por imagem gerada.

O que o Nano Banana Pro faz?

2K sem acréscimo. 1K e 2K custam $0.057 por imagem, gere direto em 2K; 4K custa $0.1 por imagem, reserve para impressão e telas grandes.
Escreva texto na imagem. Frases curtas em inglês como placas, títulos de pôster e datas podem ir direto no prompt; a placa de folha de ouro abaixo acertou as duas linhas de texto de primeira, sem nenhuma pós-produção.
Até 8 imagens de referência. Apenas com o prompt é geração a partir de texto; adicione image_input e vira edição ou fusão de várias imagens, com o mesmo ID de modelo, sem precisar de dois conjuntos de código.
10 proporções mais auto. Proporções comuns como 1:1, 4:5, 3:4, 9:16, 16:9 e 21:9 estão disponíveis. Para imagens alongadas como 1:4 e 8:1, ou para enviar mais de 8 imagens de referência de uma vez, escolha o Nano Banana 2 (até 14 imagens).

Imagem original do Nano Banana Pro, sem retoques, saída 1536×2752.

A hand-painted gold-leaf sign in a modern specialty coffee shop window, elegant serif lettering reading 'MORNING BREW CO.' with a small script subtitle 'est. 2024' beneath it, warm natural daylight streaming through the glass, soft bokeh reflections of a city street, photorealistic commercial photography, crisp perfectly legible typography with correct spelling, shallow depth of field, editorial lighting

Gerar com este prompt →, escolha proporção 9:16 e resolução 2K.

Dois caminhos para começar: teste online ou API?

Se quer ver o resultado primeiro, escolha o teste online; se vai 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)

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

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

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

2K custa $0.057 por imagem; com $10 dá para gerar cerca de 175 imagens. Na promoção limitada do Dia do Programador com 50% de desconto até 2026-11-09 00:00 (horário de Pequim), 1K e 2K saem por $0.0285 cada, e os mesmos $10 geram cerca de 350 imagens. 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-pro",
    "input": {
      "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
      "aspect_ratio": "16:9",
      "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 --fail-with-body -sS https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Somente prompt é obrigatório. aspect_ratio tem padrão auto, resolution tem padrão 1K, output_format tem padrão png, e também é possível escolher jpg. 1K e 2K têm o mesmo preço; recomenda-se incluir "resolution": "2K" em toda requisição.

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 estourar o tempo, guarde o taskId e continue consultando:

import os
import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "nano-banana-pro",
    "input": {
        "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
        "aspect_ratio": "16:9",
        "resolution": "2K",
        "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-pro.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 um campo

Adicione image_input dentro de input e a mesma requisição vira edição. Abaixo usamos um pôster de museu de ciências gerado pelo Nano Banana Pro como imagem de referência, alterando apenas a linha da data:

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-pro",
    "input": {
      "prompt": "Keep this exact poster: layout, planet, observatory, visitor, colors and headline. Change only the date line to SAT 24 OCT in the same typography and color. No other words.",
      "image_input": ["https://static.hiapi.ai/blog/gpt-image-2-vs-nano-banana-pro/0dba86ff979d-nano-pro-science.png"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

image_input aceita até 8 URLs públicas, com suporte a JPEG, PNG e WebP. No prompt, separe o que será "alterado" do que será "preservado"; quanto mais específicos os itens preservados, mais fiel a imagem original permanece.

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

Use callback no servidor. Adicione no nível superior do corpo da requisição "callback": {"url": "https://yourapp.com/webhook", "when": "final"}; a notificação é enviada automaticamente ao fim da tarefa, dispensando o polling; callbacks podem chegar duplicados, então deduplique por taskId.
Não repita o POST em caso de timeout. Cada POST /v1/tasks cria uma nova tarefa e é cobrado separadamente. Guarde o taskId primeiro e faça deduplicação no seu próprio sistema antes de tentar novamente.
Escreva resolution explicitamente em cada requisição. O padrão é 1K, e 2K tem o mesmo preço; na versão final escolha diretamente 2K; 4K tem preço unitário maior, use apenas na etapa de entrega.

Erros comuns, um por linha

400, campo não permitido → nome do campo escrito errado, ou uso de campo de outro modelo (como image_urls) → troque por image_input.
400, valor de aspect_ratio inválido → proporção fora da lista (como 8:1) → escolha uma entre as 10 proporções e auto; para imagens alongadas, mude para o Nano Banana 2.
401 → Key ausente, incorreta ou revogada → verifique o cabeçalho Authorization: Bearer sk-... e, se necessário, crie uma nova Key no console.
Criação bem-sucedida, mas tarefa em fail → veja o erro retornado pela tarefa; se a imagem de referência não abrir ou o formato não for suportado, troque por um JPEG, PNG ou WebP acessível publicamente e envie novamente.
Link da imagem expirado e inacessível → o link de saída tem prazo de validade → baixe imediatamente ao obter o resultado e guarde o arquivo em si.

Tarefas com falha não são cobradas.

Perguntas frequentes

Como escolher entre Nano Banana Pro e Nano Banana 2? Em 2K, os dois custam o mesmo: $0.057 por imagem. Para proporções alongadas ou mais de 8 imagens de referência, escolha o Nano Banana 2; para gerar a imagem principal de marca com a linha de topo da série Nano Banana, escolha o Pro.

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 8 imagens de referência custa o mesmo.

É possível migrar diretamente do Nano Banana 2? Sim. Os nomes dos campos são os mesmos (prompt, image_input, aspect_ratio, resolution, output_format); basta alterar model para nano-banana-pro; desde que a proporção esteja entre as 10 suportadas pelo Pro.

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

Artigos da série Nano Banana Pro

Teste agora: clique no Gerar com este prompt → abaixo da imagem da placa acima; o prompt já está preenchido, escolha 9:16 e 2K, troque o texto entre aspas pelo nome da sua loja e execute.

EtiquetasGeração de Imagens guia-da-api Integração via API Tutorial