A geração de imagens pela API Nano Banana 2 cobra em caso de falha? Análise completa de 3 cenários

title: "A API Nano Banana 2 cobra por imagens que falham na geração?"
description: "Entenda como funciona a cobrança da API Nano Banana 2 (Gemini 3.1 Flash Image) em casos de falha e por que você não paga por solicitações bloqueadas por segurança."

A API Nano Banana 2 cobra por imagens que falham na geração? Essa é uma das primeiras "dúvidas financeiras" que muitos desenvolvedores encontram ao integrar o Google Gemini 3.1 Flash Image (Nano Banana 2). Especialmente quando o retorno contém finishReason: IMAGE_SAFETY, blockReason: OTHER ou avisos como "A imagem fornecida parece ser um documento de identidade… não posso modificá-la", muita gente se pergunta: se a imagem não foi gerada, ainda preciso pagar?

Vamos direto ao ponto: na grande maioria dos cenários de recusa por segurança de conteúdo, a API Nano Banana 2 não cobra pela geração da imagem. Além disso, quando o finishMessage inclui explicitamente a frase "You will not be charged for this request", o Google determina automaticamente que a solicitação é isenta de cobrança. Este artigo, baseado na documentação oficial do Gemini e nas discussões mais recentes do Fórum de Desenvolvedores, analisa as 3 principais situações de falha e explica como funciona a cobrança ao utilizar a API via plataforma APIYI.

Princípios básicos de cobrança em falhas da API Nano Banana 2

3 fatos fundamentais sobre a cobrança da API Nano Banana 2

Antes de responder se a falha gera cobrança, é preciso entender a estrutura de custos do Nano Banana 2 — ele não funciona no modelo simples de "uma chamada, um preço", mas sim por uso baseado em tokens de entrada e saída.

Observe estes 3 pontos cruciais:

• Tokens de saída são o maior custo: O custo dos tokens de saída de uma imagem 1K é cerca de 5 a 20 vezes maior que o dos tokens de entrada. Isso significa que, se a imagem não for gerada, o valor cobrado é praticamente irrelevante.
• Tokens de entrada são muito baratos: $0,50 por 1 milhão de tokens significa que um comando (prompt) de 500 palavras custa menos de $0,0003 dólares.
• Cobrança por entrega real: Apenas solicitações que realmente geram imagens produzem custos de tokens de saída. Solicitações falhas que não geram imagens quase não geram custos.

A postura oficial do Google sobre cobranças em falhas

O Google expressou repetidamente, tanto na documentação da API Gemini quanto no fórum de desenvolvedores, um princípio básico: quando o sistema determina explicitamente que a solicitação foi bloqueada pela camada de política (Layer 2) ou quando o finishMessage indica "You will not be charged for this request", essa solicitação não é cobrada.

Esse princípio também é aplicado quando você utiliza o Nano Banana 2 via APIYI. Nossa lógica de cobrança está rigorosamente alinhada com o campo usage retornado pelo Google. Se o Google não cobra, a APIYI também não cobra, garantindo que não haja situações onde o serviço oficial isenta a cobrança, mas o provedor intermediário continue cobrando.

title: 3 situações típicas de falha na geração de imagens pela API Nano Banana 2

Caso 1: O comando é bloqueado pela Camada 1 após o envio (blockReason: SAFETY)

Esta é a interrupção mais "limpa" — a solicitação é barrada antes mesmo de chegar ao modelo de geração de imagens propriamente dito. Nesse momento, você verá na resposta da API:

{
  "promptFeedback": {
    "blockReason": "SAFETY",
    "safetyRatings": [
      {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "HIGH"}
    ]
  }
}

Cobrança: Sem cobrança ou apenas uma fração minúscula de tokens de entrada. Como o modelo não realizou a inferência e nenhuma parte da saída foi gerada, o custo dos tokens de entrada por si só é irrisório (0,5 dólares por milhão).

Condição de gatilho: O comando atinge o limite configurável das categorias de segurança, como a presença direta de termos sensíveis relacionados a violência, ódio ou conteúdo sexual.

Contramedida: Você pode contornar a Camada 1 ajustando os parâmetros de safety_settings para BLOCK_NONE ou OFF, mas isso não ignorará a Camada 2, que discutiremos a seguir.

Caso 2: Bloqueio pela política da Camada 2 após a geração da imagem (finishReason: IMAGE_SAFETY)

Este é o tipo de falha mais comum para desenvolvedores, correspondendo à mensagem que o usuário recebe: "A imagem que você forneceu parece ser um documento de identificação (como uma carteira de motorista), por isso não posso modificá-la". Exemplo de retorno:

{
  "candidates": [{
    "finishReason": "IMAGE_SAFETY",
    "finishMessage": "Não consigo concluir sua solicitação de edição de imagem. Como a imagem fornecida parece ser um documento de identificação pessoal (como uma carteira de motorista), não posso modificar, regenerar ou editar recursos de segurança específicos (como selos, marcas d'água ou assinaturas) conforme solicitado."
  }]
}

Cobrança: Os tokens de entrada são cobrados normalmente, mas os tokens de saída da imagem são quase zero. Embora o modelo tenha concluído a inferência, a imagem final não foi gerada, resultando apenas em uma taxa mínima de entrada na sua conta (geralmente < $0,001).

Condição de gatilho: Ocorre quando políticas não configuráveis da Camada 2 são atingidas. Os casos típicos incluem:

• Solicitações de edição de documentos de identidade (CNH, passaporte, RG, etc.)
• Geração de imagens realistas de figuras públicas famosas
• Conteúdos, logotipos ou marcas protegidos por direitos autorais
• Conteúdo sensível relacionado à segurança infantil

Contramedida: A Camada 2 não pode ser contornada via parâmetros de API. A única solução é reescrever o comando, removendo elementos que violem as políticas de proteção.

Caso 3: O modelo decide não gerar (finishMessage indica claramente a ausência de cobrança)

Esta é a recusa mais "suave" do Google — o retorno apresenta uma mensagem em inglês bastante característica:

{
  "candidates": [{
    "finishMessage": "Unable to show the generated image. The model could not generate the image based on the prompt provided. You will not be charged for this request. Try rephrasing the prompt. If you think this was an error, send feedback"
  }]
}

Cobrança: Solicitação totalmente gratuita. Este é um compromisso claro que o Google faz no corpo da resposta. Tanto na API oficial quanto em plataformas de agregação compatíveis, como a APIYI (apiyi.com), o processamento será feito sem cobrança.

Condição de gatilho:

• O modelo determina que o comando está vago demais ou não consegue gerar um resultado claro
• O modelo executou a inferência, mas não conseguiu produzir uma imagem válida
• O comando disparou avaliações de segurança internas não divulgadas pelo Google

Contramedida: Basta reescrever o comando e tentar novamente; não há necessidade de se preocupar com custos extras nessas tentativas.

description: Guia técnico sobre como a API do Nano Banana 2 lida com cobranças em cenários de falha, incluindo tabelas de custos e práticas recomendadas para desenvolvedores.

Tabela comparativa de custos em cenários de falha da API Nano Banana 2

Comparativo de custos: 3 tipos de falha vs. sucesso normal

🎯 Resumo principal: Em todos os cenários de falha conhecidos do Nano Banana 2, o desenvolvedor nunca paga pelo "custo total de geração da imagem". Mesmo no cenário de falha mais caro (Camada 2), o custo é inferior a 1% de uma geração bem-sucedida. Ao utilizar o serviço proxy de API da APIYI (apiyi.com), a plataforma repassa integralmente os campos de uso do Google, mantendo as regras de cobrança alinhadas com as oficiais.

Por que os desenvolvedores ainda "sentem que estão sendo cobrados"?

Alguns desenvolvedores relatam que "a imagem não foi gerada, mas o saldo diminuiu" — isso geralmente ocorre devido a estes 3 equívocos:

• Atraso na fatura: O faturamento do Google geralmente tem uma janela de agregação com atraso de 24 a 48 horas. A cobrança vista agora pode ser o processamento tardio de solicitações bem-sucedidas anteriores.
• Acúmulo de solicitações em lote: Uma única falha pode custar apenas $0.0003, mas se ocorrerem 1.000 falhas consecutivas em um curto intervalo, uma cobrança visível de $0.30 aparecerá.
• Prompt de entrada muito longo: Ao enviar solicitações com imagens de referência muito grandes (por exemplo, uma imagem base 4K), os tokens de entrada podem inflar para dezenas de milhares. Mesmo se a solicitação falhar, o custo de entrada será maior que o habitual.

💡 Dica de monitoramento de custos: Recomendamos analisar o campo usageMetadata diretamente na camada de invocação do modelo e registrar o promptTokenCount, candidatesTokenCount e totalTokenCount de cada solicitação. No painel da APIYI (apiyi.com), também fornecemos consultas detalhadas de tokens por invocação do modelo, permitindo localizar rapidamente "qual falha gerou uma cobrança atípica".

Método de validação de código para custos em falhas da API Nano Banana 2

Obtendo informações precisas de custo via Python SDK

from openai import OpenAI

# Inicialização do cliente com a APIYI
client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.apiyi.com/v1"
)

response = client.images.generate(
    model="gemini-3.1-flash-image",
    prompt="Por favor, modifique o campo de sexo deste documento de identidade",
    n=1,
    size="1024x1024"
)

# Verifica se o campo de uso está presente
if hasattr(response, "usage"):
    print("Tokens de entrada:", response.usage.prompt_tokens)
    print("Tokens de saída:", response.usage.completion_tokens)
    print("Tokens totais:", response.usage.total_tokens)

for item in response.data:
    if getattr(item, "finish_reason", None) == "IMAGE_SAFETY":
        print("Bloqueio da Camada 2 atingido, sem cobrança na saída")
    elif "not be charged" in (getattr(item, "finish_message", "") or ""):
        print("Google declarou explicitamente a isenção de cobrança")

import time
from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.apiyi.com/v1"
)

NO_CHARGE_PHRASES = ["You will not be charged", "not be charged for this request"]
LAYER2_FINISH_REASONS = {"IMAGE_SAFETY", "IMAGE_PROHIBITED_CONTENT", "OTHER"}

def generate_with_retry(prompt: str, max_retry: int = 3):
    for attempt in range(1, max_retry + 1):
        try:
            response = client.images.generate(
                model="gemini-3.1-flash-image",
                prompt=prompt,
                size="1024x1024"
            )

            item = response.data[0]
            finish_reason = getattr(item, "finish_reason", "")
            finish_message = getattr(item, "finish_message", "") or ""

            # Verifica se a mensagem indica isenção de cobrança
            if any(p in finish_message for p in NO_CHARGE_PHRASES):
                print(f"[Tentativa {attempt}] Google declarou isenção, trocando comando para retentar")
                return None
            # Verifica bloqueio de camada 2
            if finish_reason in LAYER2_FINISH_REASONS:
                print(f"[Tentativa {attempt}] Bloqueio de política da Camada 2, sem cobrança de saída")
                return None

            return item.url

        except Exception as e:
            print(f"[Tentativa {attempt}] Erro: {e}")
            time.sleep(2 ** attempt)

    return None

url = generate_with_retry("Um gato laranja caminhando em um jardim japonês, estilo ukiyo-e")
print("Resultado final:", url)

Como validar a "cobrança zero" na fatura real

Recomendamos usar a funcionalidade de detalhes de solicitação no painel da APIYI (apiyi.com) para uma dupla verificação:

1. Registre nos seus logs locais o request_id, finishReason e usage de cada solicitação que falhar.
2. No painel da APIYI, verifique o custo correspondente por request_id.
3. Compare os valores — caso haja discrepâncias, entre em contato com o suporte ao cliente para uma auditoria.

Como a plataforma APIYI repassa os campos nativos de uso do Google, a probabilidade de inconsistências é baixíssima. No entanto, esse mecanismo de verificação por log duplo ajuda usuários corporativos a atenderem requisitos de auditoria financeira.

Comparativo das regras de cobrança em falhas da API Nano Banana 2 e outras plataformas

Comparativo de cobrança em falhas das principais APIs de geração de imagens

A vantagem única do Nano Banana 2 reside na clareza dos sinais de falha — os campos finishReason e finishMessage permitem que desenvolvedores realizem uma verificação programática se uma solicitação gerou custo, algo que em outras plataformas exigiria tentativas exaustivas para se chegar a uma conclusão.

🎯 Sugestão de escolha: Se o seu negócio possui requisitos rígidos para "previsibilidade de falhas" (como cenários de alta frequência ou conteúdo gerado pelo usuário – UGC), recomendo priorizar o Nano Banana 2. Ao integrar via APIYI (apiyi.com), você não só garante o benefício de não cobrança em falhas (seguindo o padrão oficial), como também evita manter lógicas de faturamento específicas para cada plataforma.

Melhores práticas para cenários de falha na API Nano Banana 2

3 dicas de otimização de comando para reduzir falhas inválidas

Embora as falhas quase nunca gerem custos, taxas de erro elevadas prejudicam a experiência do usuário e aumentam a latência. Aqui estão 3 dicas validadas na prática:

Divisão de falhas e rastreamento de custos

Para ambientes de produção, recomendamos construir um log de triagem de falhas:

• Intercepção de Camada 1: Marcado como "Risco de comando", não tente novamente, solicite ao usuário que modifique.
• Intercepção de Camada 2: Marcado como "Conflito de política", não tente novamente, solicite troca de conteúdo.
• finishMessage sem cobrança: Marcado como "Limite de capacidade do modelo", reescreva automaticamente e tente novamente 1 vez.
• Rede/Timeout: Marcado como "Falha de infraestrutura", tente novamente com recuo exponencial.

Utilizando o painel de detalhes de invocação e relatório de consumo de tokens do APIYI (apiyi.com), você consegue diagnosticar rapidamente se o problema é o comando ou uma limitação do modelo, mantendo o custo médio por imagem gerada dentro de uma faixa razoável.

Garantia de faturamento para cenários corporativos

Para usuários corporativos, recomendamos combinar as 3 práticas abaixo para garantir transparência na cobrança:

• Comparação de logs duplos: Validação bidirecional entre o log de uso local e o log da plataforma APIYI.
• Alertas de orçamento: Defina um limite diário no painel do APIYI (apiyi.com); ao exceder, a chave será desativada automaticamente.
• Chaves isoladas por departamento: Use uma chave API dedicada para cada linha de negócio para contabilizar custos separadamente.
• Auditoria mensal: Selecione aleatoriamente 10 a 20 registros de falha mensalmente para confirmar se a cobrança está alinhada com as regras oficiais.

FAQ sobre falhas e cobranças na API do Nano Banana 2

Q1: Pedidos de geração de imagens de documentos de identidade pelo Nano Banana 2 são rejeitados; quanto custa?

Quase nada. Respostas de rejeição geralmente trazem finishReason: IMAGE_SAFETY. Nesse caso, apenas os tokens de entrada geram uma pequena taxa (geralmente < $0,001), e os tokens de saída da imagem não são cobrados de forma alguma. Ao usar a API via APIYI (apiyi.com), a plataforma transmite os dados de uso oficiais, garantindo que o valor cobrado seja exatamente o mesmo da Google.

Q2: O que significa o retorno "You will not be charged for this request"?

Esta é uma isenção de cobrança declarada explicitamente pela Google no campo finishMessage. Quando o corpo da resposta contém essa frase, o pedido inteiro é isento de custos — independentemente do tamanho da entrada ou de ter havido processamento pelo modelo. A plataforma APIYI identifica essa marcação e registra o valor como zero, evitando situações onde a "Google diz que não cobra, mas o serviço intermediário cobra por baixo dos panos".

Q3: Tentar novamente após uma falha no Nano Banana 2 aumenta os custos?

Cada tentativa é cobrada como um pedido independente. No entanto, como as falhas em si não geram custo ou geram apenas uma taxa mínima, o custo acumulado de 3 tentativas geralmente não chega a 10% do custo de uma chamada bem-sucedida. Recomendamos adicionar uma estratégia de backoff exponencial na lógica de retentativa para evitar que falhas frequentes acionem o limite de taxa (429).

Q4: Qual a diferença de cobrança entre as interceptações de Camada 1 e Camada 2?

A interceptação de Camada 1 ocorre antes da inferência do modelo e, geralmente, não tem custo. A interceptação de Camada 2 ocorre após a inferência, mas antes da saída, gerando uma cobrança mínima pelos tokens de entrada, mas sem cobrança pelos tokens de saída. Ambos os casos são considerados de "custo negligenciável".

Q5: Por que desenvolvedores relatam que o "Gemini 3.1 Pro cobra mesmo em recusas de segurança"?

Este é um caso especial: alguns modelos de texto Gemini 3.1 Pro (note que não é o modelo de imagem Nano Banana 2) injetam um "prompt de segurança oculto" ao recusar prompts inseguros e processam a inferência completa, o que resulta na cobrança dos tokens. O Nano Banana 2 (Gemini 3.1 Flash Image) não possui esse comportamento atualmente, e o faturamento de falhas em cenários de imagem permanece "quase zero".

Q6: Chamar o Nano Banana 2 pela APIYI é mais caro que pela oficial?

Não. A plataforma adota o sistema de precificação por token oficial e frequentemente oferece descontos em volume para modelos de alta demanda como o Nano Banana 2, tornando o preço real geralmente inferior ao da chamada direta. O mais importante: o pagamento direto em Reais e a conformidade fiscal da plataforma permitem que empresas brasileiras evitem preocupações com taxas de câmbio, cartões de crédito internacionais ou entidades estrangeiras.

Q7: Como determinar se uma falha resultou em "cobrança de entrada" ou se foi "totalmente gratuita"?

Basta analisar 3 campos na resposta:

• Se o finishMessage contiver "You will not be charged" → Cobrança zero
• Se blockReason: SAFETY aparecer em promptFeedback → Cobrança mínima ou zero
• Se finishReason: IMAGE_SAFETY / OTHER → Apenas tokens de entrada (valor mínimo)

Na página de detalhes de chamadas do painel da APIYI (apiyi.com), também rotulamos diretamente se cada chamada gerou custo real, sem necessidade de análise manual.

Q8: Qual é a taxa de falha do Nano Banana 2?

De acordo com dados públicos da comunidade do primeiro trimestre de 2026, a taxa de falha geral para prompts com mistura de chinês e inglês é de cerca de 5% a 8%. Destes, as "falhas de política" que atingem a Camada 2 representam 2% a 3%; o restante são recusas finishMessage (sem custo) causadas por problemas na qualidade do prompt. Isso significa que mais de 99% das chamadas com falha têm custo zero ou próximo de zero, sendo o impacto nos negócios negligenciável.

Q9: Pedidos com falha contam para o limite de taxa (RPM / TPM)?

Sim, contam. Mesmo pedidos com falha que não geram cobrança ocupam sua cota de taxa. Para operações de alta frequência, recomendamos realizar uma pré-filtragem local do prompt para reduzir a chance de atingir a Camada 2 e preservar a cota para chamadas bem-sucedidas.

Conclusão: API do Nano Banana 2 não cobra por falhas, pode testar sem medo

Voltando à pergunta inicial — A API do Nano Banana 2 cobra por falhas na geração de imagens? A resposta é clara: Na quase totalidade dos cenários de falha, não há cobrança ou cobra-se apenas uma fração mínima pelos tokens de entrada. Especialmente quando aparece finishReason: IMAGE_SAFETY ou finishMessage contendo "You will not be charged for this request", são casos de isenção total prometida pela Google.

Para os desenvolvedores, isso significa 3 coisas:

1. Segurança para testar: Seja explorando técnicas de prompt, validando estilos ou testando casos extremos, o custo do erro é quase zero.
2. Sem necessidade de contingência complexa: Não é preciso desenhar lógica de suporte contra "cobrança de erro"; a boa e velha lógica de try/retry resolve.
3. Fatura previsível: O gasto mensal é basicamente igual a imagens bem-sucedidas × custo unitário, sendo as falhas um erro de arredondamento insignificante.

Claro, não cobrar por falhas não significa "tentar infinitamente" — as tentativas ocupam limite de taxa e aumentam o tempo de espera do usuário. A melhor prática é: classificar a falha e aplicar a estratégia — interceptações de Camada 1/2 devem avisar o usuário para alterar o prompt, enquanto recusas finishMessage (gratuitas) podem ser automaticamente reescritas e reenviadas. Combinado com os logs de chamada e alertas de orçamento da APIYI, você pode tornar os custos da sua operação de imagem visíveis em tempo real.

Se você está avaliando o Nano Banana 2 ou o Nano Banana Pro para produção, recomendamos abrir uma conta de teste na APIYI e rodar os 3 cenários de falha descritos aqui com seus próprios prompts; os dados reais de cobrança serão a resposta mais convincente.

Autor: Equipe APIYI — Focada em integração conforme de APIs de Modelos de Linguagem Grandes e serviços de geração de imagens da série Nano Banana.