Migrar de Nano Banana 2 para 2.1: o que muda na API

O Nano Banana 2.1 continua usando a interface de tarefas assíncronas da HiAPI, então a migração de código é pequena, mas algumas restrições de entrada precisam ser verificadas novamente. A mudança mais evidente é o valor de model; a quantidade de imagens de referência e o tamanho máximo por arquivo também mudaram. Os preços devem ser consultados na página em tempo real e nos registros de tarefas antes do lançamento.

Este artigo foi organizado com base no contrato de interface atualmente exibido na página do modelo Nano Banana 2 e na página do modelo Nano Banana 2.1. Os exemplos usam a estrutura de requisição da documentação atual; antes de redirecionar o tráfego de produção, valide em uma conta de teste com saldo.

A menor mudança é substituir o model

As duas versões criam tarefas via assíncrona:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "A clean e-commerce product photograph of a minimalist amber glass skincare serum bottle with a black dropper cap, blank unlabeled bottle, centered on a white marble pedestal, soft studio lighting, warm white background, no lettering",
      "resolution": "1K",
      "aspect_ratio": "1:1",
      "output_format": "png"
    }
  }'

Se a requisição original era de texto para imagem, o foco da migração é alterar o model:

- "model": "nano-banana-2"
+ "model": "gemini-nano-banana-2.1"

A interface na documentação continua sendo POST /v1/tasks. Depois que a requisição é aceita, a interface de criação retorna um ID de tarefa, usado para polling ou callback. O fluxo existente de polling ou callback pode continuar sendo usado, mas ainda é preciso verificar os campos atuais de status e resultado da tarefa.

Campos que podem ser mantidos e limites que precisam ser verificados novamente

O contrato atual da 2.1 mantém os campos de entrada comuns da versão 2: prompt, image_input opcional, aspect_ratio, resolution e output_format. O teste rápido com saldo abaixo aceitou tanto texto para imagem quanto imagem de referência; ao fazer a troca oficial, ainda é preciso verificar o contrato em tempo real conforme a versão muda.

O limite de imagens de referência mudou. A página do Nano Banana 2 informa no máximo 14 imagens e 10 MB por imagem; a página da 2.1 informa no máximo 10 imagens e 30 MB por imagem. Apenas substituir o ID do modelo e continuar encaminhando as 14 imagens antigas fará a requisição exceder o limite da nova versão. O cliente deve verificar a quantidade conforme o novo limite e decidir se trunca ou avisa o usuário diretamente.

A página do modelo 2.1 não expõe a entrada mask. Na migração, não adicione o campo mask por conta própria, a menos que a documentação da interface o forneça explicitamente mais tarde. Para edição de imagem, use image_input para enviar a imagem original e, no prompt, descreva claramente o que deve ser alterado e quais detalhes devem ser preservados.

{
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "Keep the amber glass serum bottle and black dropper cap from the reference image. Place it on a sunlit wooden bathroom counter beside a folded cream linen towel and eucalyptus, preserving the bottle shape and blank label.",
    "image_input": ["https://static.hiapi.ai/blog/gemini-nano-banana-2-1-ecommerce-product-images/studio.jpg"],
    "resolution": "1K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}

Esta requisição foi concluída com sucesso no teste rápido com saldo; a imagem de resultado pode ser vista aqui. A página da 2.1 atualmente informa que as imagens de referência suportam JPEG, PNG e WebP, com no máximo 30 MB por imagem.

O preço deve ser verificado em duas camadas

Na verificação da página do modelo em 2026-10-16, as faixas de 1K, 2K e 4K do Nano Banana 2.1 exibiam 44, 72 e 116 créditos, respectivamente. Antes de planejar o orçamento, consulte a página de preços em tempo real e a página do modelo; a leitura de cobrança ainda precisa de verificação independente.

Não registre preços promocionais ou números vistos em alguma página de conta como preço fixo de longo prazo. Na validação de lançamento, registre a resolução, o valor exibido antes do envio e a cobrança efetiva após a conclusão da tarefa.

Alternar dois model IDs com o mesmo prompt

Para verificar o caminho de migração, enviamos o mesmo prompt 1K, 1:1 usando os dois model IDs públicos. As duas requisições criaram tarefas com sucesso e atingiram success. As garrafas e os detalhes da bancada nas duas imagens são diferentes; portanto, esse conjunto de resultados serve para verificar roteamento e tratamento de resultados, não é suficiente para classificar qualidade de imagem nem prova que a identidade do produto é a mesma.

Prompt usado nas duas requisições:

A clean e-commerce product photograph of a minimalist amber glass skincare serum bottle with a black dropper cap, blank unlabeled bottle, centered on a white marble pedestal, soft studio lighting, warm white background, no lettering

Rota	Model ID	Resultado
Nano Banana 2	nano-banana-2	1K, 1:1, PNG, tarefa concluída com sucesso
Nano Banana 2.1	gemini-nano-banana-2.1	1K, 1:1, PNG, tarefa concluída com sucesso

Esta validação de migração mostra que o model ID da 2.1 aceita a estrutura atual de tarefas de texto para imagem da documentação e retorna imagens pelo mesmo fluxo assíncrono. As diferenças visuais em um único conjunto de amostras são apenas observações e não devem ser tratadas como resultado de comparação entre modelos.

Lista de verificação antes do lançamento

1. Substitua nano-banana-2 pelo ID exato da nova versão: gemini-nano-banana-2.1.
2. Mantenha o fluxo assíncrono POST /v1/tasks e o tratamento existente de status de tarefa.
3. Valide que image_input é um array de URLs públicas de imagens, com no máximo 10 imagens.
4. Troque a suposição antiga de 10 MB por imagem pelo limite de 30 MB atualmente informado na página da 2.1.
5. Mantenha prompt, aspect_ratio, resolution, output_format e remova campos sem base documental, como mask.
6. Na conta de teste, envie uma tarefa somente de texto e uma tarefa de edição com imagem de referência, e salve a requisição, o ID da tarefa, o status final, a URL do resultado e o valor cobrado.
7. Compare uma vez com os resultados e o tratamento de erros da versão antiga e, só então, troque o modelo padrão para todos os usuários.

Leitura de cobrança e manutenção futura

O teste rápido acima já validou a estrutura de requisição de texto para imagem e imagem para imagem, a criação de tarefa, o estado final de sucesso e a URL do resultado. A cobrança não foi lida de forma independente a partir da conclusão da tarefa; o custo de produção ainda deve ser baseado na página de preços em tempo real e nos registros de tarefas. Se o contrato ou os limites da página do modelo mudarem antes do lançamento, verifique novamente.

Perguntas frequentes

É preciso trocar a interface para migrar para o Nano Banana 2.1?

Atualmente as duas páginas de modelo usam POST /v1/tasks. Primeiro altere o model ID e depois valide a entrada e a estrutura de retorno com requisições reais.

Ainda é possível usar nano-banana-2?

Esse ID ainda representa o Nano Banana 2. Para chamar a 2.1, use gemini-nano-banana-2.1.

Ainda é possível enviar 14 imagens de referência após a migração?

O limite atualmente listado na página do modelo 2.1 é 10 imagens. Ao ultrapassar a quantidade, o cliente deve reduzir ou rejeitar a requisição.

A edição com imagem de referência exige outra interface?

Atualmente a página não tem uma interface separada de edição. Continue usando o mesmo model ID, adicione image_input e explique no prompt o que deve ser alterado e quais detalhes devem ser preservados.

A 2.1 é mais barata para todas as contas?

A página pública atualmente mostra números de créditos padrão mais baixos para cada resolução, mas os preços podem ser ajustados e a página também pode ser afetada pelo status da conta ou por promoções. Antes de concluir algo sobre custo, verifique ao mesmo tempo o preço em tempo real e o registro de cobrança após a conclusão da tarefa.

Leitura complementar

• Tutorial de integração com a API do Nano Banana 2.1
• Preços da API do Nano Banana 2.1
• Como usar a API do Nano Banana 2

Experimente o Nano Banana 2.1 na página de modelos da HiAPI.