Guia da API Nano Banana: Geração e Edição de Imagens no TokenLab

A API Nano Banana possui três IDs de modelo tarifados no TokenLab, e o mais barato custa cerca de metade por imagem em comparação com o intermediário. O erro caro raramente é a escolha do modelo. É enviar uma solicitação de edição para o endpoint errado ou tentar novamente uma chamada de criação que já gerou uma tarefa. Este guia cobre os IDs exatos, uma chamada funcional de texto para imagem, uma chamada de imagem de referência, polling assíncrono, erros esperados e como a cobrança é definida. Os preços e as listas de campos foram lidos em 03/10/2026, portanto, confirme-os novamente antes de colocar em produção.

Principais pontos

• Envie o ID exato: nano-banana-2, nano-banana-2-lite ou nano-banana-pro. Nomes de exibição não são aliases de solicitação.
• O trabalho de imagem de referência para o Nano Banana vai para POST /v1/images/generations com operation: "image-to-image" e image_urls. Ele não vai para /v1/images/edits ou /v1/chat/completions.
• Os preços base que lemos em 03/10/2026 são $0,0168, $0,0335 e $0,067 por imagem para os IDs lite, standard e pro. Cada modelo tem uma faixa de preço, então confirme o nível exato em Usage.
• Uma resposta de criação com task_id, status: "pending" ou poll_url significa que você deve fazer polling em GET /v1/tasks/{id} até que esteja completed ou failed.
• Uma leitura de status retorna HTTP 200 mesmo quando a tarefa falhou. Verifique o campo status da tarefa, não o código HTTP.
• As cobranças finais ficam em Usage e no billing_transaction_id, não em uma tabela de preços copiada.

Modelos da API Nano Banana, unidades de preço e para que serve cada um

Ao compararmos o rascunho anterior deste guia com a documentação atual, encontramos três problemas. Ele listava modelos sem preços. Ele enviava uma edição do Nano Banana via chat completions. Ele consultava o catálogo com um filtro que o guia de imagens não usa. A tabela abaixo corrige o primeiro. As seções posteriores corrigem os outros dois.

ID do Modelo	Melhor para	Unidade de precificação	Preço TokenLab (USD)	Fonte, observado
nano-banana-2	Texto para imagem e imagem para imagem com aspect_ratio e resolution (1k, 2k, 4k). Lançado em 26/02/2026.	per_image	$0,0335 por solicitação. Faixa de $0,0225 a $0,0755.	API do modelo ao vivo, 03/10/2026
nano-banana-2-lite	Texto para imagem e imagem para imagem mais baratos. A entrada de preço que vimos cobre o nível 1k.	per_image	$0,0168 por solicitação. Mínimo e máximo ambos $0,0168.	API do modelo ao vivo, 03/10/2026
nano-banana-pro	Texto para imagem, imagem para imagem e edição de imagem com aspect_ratio e resolution.	per_image	$0,067 por solicitação. Faixa de $0,067 a $0,12.	API do modelo ao vivo, 03/10/2026
nano-banana	Texto para imagem apenas com aspect_ratio. Sem seleção pública de resolution.	Não consta em nossas evidências	Verifique a página do modelo ou o endpoint de precificação	Catálogo, 02/10/2026; Documentação de Create Image, 03/10/2026

Todos os preços acima possuem is_lock_price: true e foram atualizados em 02/10/2026T16:53:30.068Z. Três detalhes importam antes de você escolher um:

• Níveis de resolução alteram o preço. A API ao vivo mostra uma faixa para nano-banana-2 e nano-banana-pro, mas nossas evidências não mapeiam cada nível para uma resolução. Não presuma que 1k é o preço base. Leia as entradas de precificação do seu modelo.
• A saída de texto tem seu próprio preço por token. Tanto nano-banana-2 quanto nano-banana-pro possuem uma entrada native-gemini-text-output. Ela se aplica quando outputModality é text. Para nano-banana-2, lista 0,25 de entrada e 1,5 de saída. Para nano-banana-pro, lista 1 de entrada e 6 de saída. A unidade é per_token. Confirme a escala em GET /v1/models/:model/pricing antes de orçar com base nisso.
• O Lite não lista formato de solicitação aceito. O registro ao vivo para nano-banana-2-lite diz "não listado". Leia seus detalhes antes de desenvolver com ele.

Para um orçamento aproximado, multiplicamos o preço base pelo volume. Estas são estimativas ao preço base, não cotações:

• 100 imagens no nano-banana-2-lite: 100 × $0,0168 = $1,68.
• 100 imagens no nano-banana-2: 100 × $0,0335 = $3,35.
• 100 imagens no nano-banana-pro: 100 × $0,067 = $6,70.

Níveis de resolução mais altos aumentarão esses números.

Para listar os modelos de imagem atuais você mesmo, chame o endpoint que o guia de geração de imagem usa. O rascunho anterior usava category=image, o que o guia não documenta.

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Para operações, preços e ciclo de vida de um modelo, use Get a Model. Você também pode navegar pelo diretório de modelos do TokenLab.

Envie uma solicitação de texto para imagem com a API Nano Banana

Crie uma chave de API no painel do TokenLab e exporte-a:

export TOKENLAB_API_KEY="your-tokenlab-api-key"

Sempre envie o model. A referência de Create Image diz que as APIs de imagem não escolhem um padrão. Um modelo ausente retorna um 400 com param: "model".

Esta solicitação usa apenas campos que a documentação lista para as famílias de imagem do Google. Mantivemos resolution em 1k porque o nano-banana-2 documenta 1k, 2k e 4k.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

O flag --max-time 120 corresponde à documentação. Eles dizem que solicitações de alta resolução podem levar quase um minuto ou mais, então defina o timeout do seu cliente para pelo menos 120 segundos. A documentação diz que size é um alias de compatibilidade para famílias de imagem do Google, mas eles recomendam aspect_ratio diretamente.

Um sucesso síncrono retorna a imagem finalizada inline. Os valores de placeholder abaixo mostram apenas a estrutura documentada:

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

Leia nesta ordem:

1. Se o corpo tiver task_id, status: "pending" ou poll_url, você tem uma tarefa, não uma imagem. Vá para a seção de polling.
2. Caso contrário, leia data[0].url. Com response_format: "b64_json", leia data[0].b64_json.
3. created é um timestamp Unix. revised_prompt aparece apenas quando o modelo retorna um, então não o exija.
4. Armazene a URL da imagem, seu próprio ID de trabalho, o modelo e o request_id dos cabeçalhos da resposta.

URLs de imagens geradas podem ser mantidas como cópias de mídia por 30 dias. Verifique media_retention.items para o status de cada item e expires_at. Cópias pendentes ou com falha não são garantidas, então copie o arquivo para seu próprio armazenamento se precisar dele por mais tempo. O guia de retenção de dados tem os detalhes.

Edite uma imagem com uma URL de referência

Imagine uma equipe de catálogo que deseja a mesma foto de produto em um fundo de estúdio limpo. O movimento tentador é /v1/images/edits. A documentação descarta isso. As solicitações de imagem de referência do Nano Banana são expostas em /v1/images/generations com operation: "image-to-image". /v1/images/edits não é o caminho correto para elas.

Esta solicitação vem do guia de geração de imagem, com nano-banana-2 como modelo:

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Regras que seguimos com esta estrutura:

• Envie exatamente os campos de referência documentados. Use image_url, image_urls ou reference_image_urls em JSON. Não envie images[] ou file_id de nível superior. Eles pertencem ao fluxo de edição e são rejeitados neste endpoint.
• Use URLs públicas. Elas devem ser http ou https, sem credenciais incorporadas, sem fragmentos e sem hosts de rede privada. Evite URLs assinadas que podem expirar antes que o processamento comece.
• Use multipart para fontes privadas. A documentação oferece um arquivo image multipart para fontes que são privadas ou protegidas por cabeçalho.
• Combine resolution com o modelo. A documentação diz que nano-banana-pro pode incluí-lo e nano-banana-edit deve omiti-lo. A documentação também nomeia nano-banana-edit como um modelo de imagem de referência, mas esse ID não está no catálogo que buscamos em 02/10/2026. Verifique qualquer ID em /v1/models antes de usá-lo.

O exemplo de edição de chat-completions do artigo original desapareceu. O registro ao vivo lista gemini_generate_content como o formato aceito para nano-banana-2 e nano-banana-pro. Nossas evidências não documentam um caminho de edição de imagem via chat-completions.

Inpainting baseado em máscara e parâmetros como strength não estão documentados para o Nano Banana em nossas evidências. Inspecione GET /v1/models/{model} antes de enviá-los.

Quando uma solicitação de imagem se torna uma tarefa e como fazer o polling

Uma chamada de criação de imagem é síncrona ou assíncrona, e a resposta informa qual. O guia de trabalhos assíncronos lista os campos de gatilho: task_id, status: "pending" ou poll_url. Se algum aparecer, o array data[] está vazio e o trabalho ainda está em execução.

Nossas evidências documentam o flag de solicitação async: true apenas para gpt-image-2 e modelos de imagem oficiais FLUX/BFL. Ele não documenta para os IDs do Nano Banana. Não o adicione a uma solicitação do Nano Banana. Trate uma resposta de tarefa se ela retornar e verifique os detalhes do modelo se precisar de comportamento assíncrono.

Imagine uma atualização de navegador que reenvia a chamada de criação após uma resposta lenta. Você agora paga por duas gerações. A documentação diz que a maioria das gerações duplicadas vem dessa tentativa de repetição. Siga esta ordem:

1. Salve os IDs imediatamente. Armazene id ou task_id, poll_url, o modelo, o endpoint e seu próprio ID de trabalho. id e task_id são o mesmo valor.
2. Faça o polling da URL. Use poll_url quando presente. Caso contrário, chame a rota fixa:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. Faça o polling a cada 5–10 segundos. O guia diz que isso geralmente é suficiente para trabalhos de mídia longos.
2. Conheça os status. Eles são pending, processing, completed e failed. Uma tarefa cancelada mostra failed com cancelled: true.
3. Pare em um status terminal. Em completed, leia data[].url. Resultados de imagem assíncronos são apenas URLs, nunca b64_json. Em failed, leia error e error_details.
4. Trate timeouts com segurança. Se uma chamada de criação expirar antes de você ver uma resposta, verifique o request_id e procure por uma tarefa antes de tentar novamente. Se você salvou um ID de tarefa, retome o polling dele. Se um polling de status falhar, tente novamente esse polling com backoff e não recrie.

Uma leitura de status retorna HTTP 200 mesmo para uma tarefa com falha. Tarefas com falha podem incluir error_details com status, type, code, message, param e retryable. Por exemplo, error_details.status: 400 com param: "size" significa que a solicitação precisa de correção. Não significa que o polling em si falhou. Tentar novamente uma geração com falha cria uma nova tarefa e pode criar uma nova cobrança.

Erros a esperar e o que fazer

Trate erros por status HTTP e code, nunca por message. O guia de tratamento de erros diz que a mensagem pode mudar sem aviso. Chat Completions e Responses usam um objeto error estilo OpenAI, enquanto os formatos Gemini e Anthropic mantêm suas próprias estruturas. Não compartilhe um parser entre todas as APIs do TokenLab.

Status / code	Causa provável	O que fazer
400, param: "model"	Nenhum modelo explícito	Envie model. Liste IDs com /v1/models?recommended_for=image.
400 campo não suportado, ou unsupported_parameter	Um campo que o modelo não documenta, como resolution em um modelo sem ele	Remova o campo ou troque de modelo. Não repita sem alterações.
400 em uma imagem de referência	Endpoint errado, ou uma URL privada ou expirada	Use /v1/images/generations com image_urls. Use uma URL pública e estável.
401 invalid_api_key ou expired_api_key	Chave ausente, revogada ou expirada	Substitua a chave.
402 insufficient_balance ou quota_exceeded	Saldo muito baixo, ou a chave atingiu seu próprio limite	Adicione fundos, aumente o limite da chave ou escolha um modelo de preço menor.
403 model_not_allowed	A chave não pode usar esse modelo	Atualize a lista de modelos da chave.
404 model_not_found	ID desconhecido ou indisponível	Leia /v1/models e use um ID atual.
413 payload_too_large	Solicitação ou arquivo muito grande	Reduza a entrada.
429 rate_limit_exceeded	Muitas solicitações na janela	Aguarde pelo Retry-After, então tente novamente.
500–504, all_channels_failed	Problema de serviço ou fornecimento	Tente novamente apenas quando retryable for true. Respeite retry_after e limite as tentativas.

Um 503 all_channels_failed nem sempre significa uma interrupção. Se retryable for false e retry_after estiver faltando, a operação não tem fornecimento no nível de entrega selecionado. Repetir a solicitação não ajudará, então verifique GET /v1/models primeiro.

O polling de tarefas tem suas próprias falhas:

• 404 async_task_not_found: a tarefa expirou ou não existe mais. Verifique o task_id e poll_url salvos.
• 403 task_not_owned: a tarefa pertence a outro workspace. Verifique a qual workspace a chave de API pertence.
• Uma tarefa concluída sem URL de mídia: trate como falha. Mantenha os IDs e entre em contato com o suporte.

Ao entrar em contato com o suporte, envie request_id, task_id, billing_transaction_id quando presente, endpoint, modelo, hora e nomes de campos. Nunca envie chaves, mídia privada ou URLs assinadas.

Como a cobrança de uma solicitação de imagem é determinada

Todos os três IDs do Nano Banana tarifados usam a unidade per_image, então a cobrança principal é o preço per_request do modelo. O guia de faturamento adiciona as regras em torno disso:

• Um resultado, uma cobrança. Cada solicitação concluída é cobrada uma vez, pela opção de entrega que a produziu. TokenLab Verified usa preços públicos do TokenLab. Official usa a camada de preço oficial. Auto tenta o Verified primeiro, depois o Official.
• Níveis definem o número final. As faixas de preço ao vivo ($0,0225 a $0,0755 para nano-banana-2, $0,067 a $0,12 para nano-banana-pro) mostram que um preço fixo não cobre todas as solicitações. Níveis de resolução são o provável motor, mas confirme isso nas entradas de precificação do modelo.
• Tarefas reservam primeiro. Uma tarefa assíncrona pode reservar seu custo estimado quando aceita. Uma tarefa concluída é cobrada uma vez, e uma tarefa com falha libera ou reembolsa o valor pendente. O guia de faturamento diz que uma tarefa com falha não é cobrada.
• Um traço não é gratuito. Na página de Modelos, um traço na coluna de preço do TokenLab significa que nenhuma oferta Verified está disponível no momento.

Para confirmar uma cobrança, use estes locais:

1. GET /v1/models/:model/pricing ou a API de Precificação para o preço atual.
2. Console, que mostra a estimativa máxima antes de você confirmar a geração paga.
3. Usage para a cobrança final por modelo.
4. billing_transaction_id na resposta ou tarefa, e o cabeçalho X-Billing-Transaction-ID. Streaming e alguns formatos nativos podem expô-lo apenas no cabeçalho.

Se o Usage não mostrar a cobrança final ou o valor liberado após a conclusão de uma tarefa, envie o Request ID e o task ID para support@tokenlab.sh. Não copie os preços deste artigo para o seu código. O guia de faturamento diz para ler o preço atual quando sua aplicação precisar exibir ou comparar custos.

FAQ

Qual ID de modelo Nano Banana devo enviar para solicitações de imagem para imagem?

Os registros ao vivo listam image-to-image para nano-banana-2, nano-banana-2-lite e nano-banana-pro. A documentação também nomeia nano-banana-edit, mas ele não está no catálogo que buscamos em 02/10/2026. Envie o ID com operation: "image-to-image" e image_urls para /v1/images/generations. Execute um pequeno teste em suas próprias imagens, pois nossas evidências não têm comparação de qualidade.

Por que minha solicitação de imagem retornou um task_id em vez de uma imagem?

A chamada de criação foi executada como uma tarefa assíncrona. Procure por task_id, status: "pending" ou poll_url na resposta. Salve esses campos, então faça o polling de poll_url ou GET /v1/tasks/{id} a cada 5–10 segundos até que o status seja completed ou failed. Não envie uma segunda solicitação de criação enquanto espera.

Posso obter saída base64 de um modelo Nano Banana?

O campo response_format aceita url ou b64_json, e uma solicitação síncrona pode retornar data[].b64_json. Resultados de imagem assíncronos são apenas URLs, qualquer que seja o formato que você pediu. Verifique os detalhes do modelo selecionado para confirmar se ele aceita b64_json, pois os campos diferem por modelo.

Uma tarefa de imagem com falha é cobrada?

O guia de faturamento diz que uma tarefa com falha não é cobrada, e qualquer reserva pendente é liberada ou reembolsada. Tentar novamente uma geração com falha cria uma nova tarefa e pode criar uma nova cobrança. Confirme o resultado no Usage usando o billing_transaction_id e task_id.

Crie uma chave no painel do TokenLab, envie a solicitação de texto para imagem acima com nano-banana-2-lite e verifique a cobrança no Usage.