Nota do autor: vamos analisar campo a campo a mensagem de erro IMAGE_SAFETY retornada pela API do Nano Banana Pro, explorando o mecanismo de filtro de segurança de camada dupla, a lógica de cobrança de tokens e 8 estratégias práticas para aumentar a taxa de sucesso na geração.
Ao gerar imagens com a API do Nano Banana Pro, você pode ter se deparado com esta resposta confusa: mesmo que o seu comando não contenha nada sensível, o sistema retorna finishReason: IMAGE_SAFETY, indicando que a imagem foi bloqueada pelo filtro de segurança. O que torna tudo ainda mais estranho é que o campo thoughtsTokenCount: 173 na resposta mostra que o modelo concluiu o raciocínio, mas a imagem foi "vetada" no final. Este artigo vai dissecar cada campo desse erro, esclarecer o mecanismo de segurança de camada dupla do Google, explicar a lógica de cobrança de tokens em casos de bloqueio e mostrar como melhorar a sua taxa de sucesso.
Valor central: Ao terminar de ler, você entenderá o significado de cada campo no erro IMAGE_SAFETY, saberá se houve cobrança de tokens quando o bloqueio ocorre e aprenderá como otimizar seus comandos para elevar a taxa de sucesso para 70-80%.
Análise detalhada do erro IMAGE_SAFETY
Primeiro, vamos esclarecer o significado de cada campo nesta resposta.
| Campo | Valor | Significado |
|---|---|---|
content.parts |
null |
Nenhum conteúdo retornado (imagem bloqueada) |
finishReason |
IMAGE_SAFETY |
Gatilho da segunda camada do filtro de segurança de saída |
finishMessage |
"Unable to show…" | Aviso oficial do Google: violação da política de uso de IA generativa |
promptTokenCount |
276 | O comando consumiu 276 tokens |
candidatesTokenCount |
0 | Tokens de saída são 0 (imagem bloqueada, sem geração) |
totalTokenCount |
449 | Total de 449 tokens (276 de entrada + 173 de raciocínio) |
thoughtsTokenCount |
173 | O processo de raciocínio do modelo consumiu 173 tokens |
promptTokensDetails |
TEXT:18, IMAGE:258 | 18 tokens de texto + 258 tokens de imagem (imagem de referência) |
modelVersion |
gemini-3-pro-image-preview | Modelo Nano Banana Pro |
Os 3 sinais mais importantes do erro IMAGE_SAFETY
Sinal 1: thoughtsTokenCount: 173 — O modelo realmente pensou
Isso indica que seu comando passou pela primeira camada de verificação de segurança (entrada), e o modelo iniciou o processo de inferência (Thinking), chegando até a gerar a imagem — mas foi bloqueado pelo filtro de segurança da segunda camada na saída final. O problema não está no seu comando, mas no conteúdo que o modelo "tentou desenhar".
Sinal 2: candidatesTokenCount: 0 — Saída zero
Após o bloqueio da imagem, os tokens de saída são contados como 0. A declaração oficial do Google é "You will not be charged for blocked images" (Você não será cobrado por imagens bloqueadas). Porém, atenção: se os tokens de entrada (276) e os tokens de raciocínio (173) serão cobrados, isso depende de cada caso e da lógica de faturamento.
Sinal 3: IMAGE: 258 — Você enviou uma imagem de referência
Sua solicitação contém uma imagem de referência (consumindo 258 tokens de imagem). Isso significa que você provavelmente está realizando uma edição de imagem (imagem para imagem), e não apenas uma geração de texto para imagem. Cenários de edição de imagem geralmente possuem filtros de segurança mais rigorosos do que apenas texto, pois a própria imagem de referência também passa por uma verificação de segurança.
O mecanismo de filtragem de segurança de duas camadas do Google
Para entender o erro IMAGE_SAFETY, é fundamental compreender que a filtragem de segurança do Google não possui apenas uma, mas duas camadas — e a segunda camada não pode ser desativada.
Primeira camada: Configuração de segurança de entrada (configurável)
| Dimensão | Descrição | Configurável? |
|---|---|---|
| Local de filtragem | Entrada (comando) | Sim |
| Objeto de filtragem | Texto e imagens enviados pelo usuário | Sim |
| Configuração possível | BLOCK_NONE (sem bloqueio) | Sim |
| Comportamento após gatilho | Solicitação recusada diretamente, sem consumo de tokens | — |
Você pode definir safety_settings como BLOCK_NONE via parâmetros da API para reduzir a sensibilidade da primeira camada.
Segunda camada: Filtragem de segurança de saída (não configurável)
| Dimensão | Descrição | Configurável? |
|---|---|---|
| Local de filtragem | Saída (imagem gerada) | Não |
| Objeto de filtragem | Conteúdo da imagem gerada pelo modelo | Não |
| Pode desativar? | Não, obrigatório para todos os usuários e níveis | Não |
| Comportamento após gatilho | finishReason: IMAGE_SAFETY, parts: null |
— |
O erro IMAGE_SAFETY ocorre quando a segunda camada é acionada. Seu comando passou pela primeira camada, o modelo concluiu o raciocínio (173 tokens) e gerou a imagem — mas ela foi bloqueada pela segunda camada antes da entrega final.
O Google reconheceu oficialmente que este filtro "tornou-se mais cauteloso do que o esperado", levando a muitos bloqueios indevidos — até mesmo comandos como "um cachorro" ou "uma tigela de cereal" podem ser bloqueados.
O que acontece com a cobrança quando o IMAGE_SAFETY bloqueia uma solicitação?
Esta é a dúvida que mais preocupa os desenvolvedores.
Regras de cobrança do IMAGE_SAFETY no Nano Banana Pro
| Item de cobrança | É cobrado se bloqueado? | Explicação |
|---|---|---|
| Taxa de geração de imagem | Não é cobrado | O Google afirma claramente: "You will not be charged for blocked images" |
| Token de saída | Não é cobrado | candidatesTokenCount: 0, sem saída, sem cobrança |
| Token de entrada | Pode ser cobrado (valor ínfimo) | 276 Tokens × $0,25/M ≈ $0,00007 (desprezível) |
| Token de raciocínio | Depende da lógica de cobrança | 173 Tokens, a API do Gemini pode incluir isso nos candidatos |
Conclusão: Quando bloqueado pelo IMAGE_SAFETY, os custos principais (taxa de geração de imagem e tokens de saída) não são gerados. O custo dos tokens de entrada é extremamente baixo (menos de um décimo de milésimo de dólar), sendo praticamente irrelevante.
Garantia adicional da APIYI: Ao realizar a invocação via APIYI (apiyi.com), falhas na geração não geram cobrança — incluindo casos de bloqueio pelo IMAGE_SAFETY. Você paga apenas pelas imagens geradas com sucesso.
8 métodos para aumentar a taxa de aprovação do IMAGE_SAFETY
Já que a segunda camada de filtro de segurança não pode ser desativada, só nos resta usar métodos indiretos para aumentar a taxa de sucesso.
Método 1: Definir BLOCK_NONE para desativar a primeira camada
Primeiro, certifique-se de que a primeira camada não aplique bloqueios extras:
from google.genai import types
# Configurações de segurança para evitar bloqueios desnecessários
safety_settings = [
types.SafetySetting(
category="HARM_CATEGORY_HARASSMENT",
threshold="BLOCK_NONE"
),
types.SafetySetting(
category="HARM_CATEGORY_HATE_SPEECH",
threshold="BLOCK_NONE"
),
types.SafetySetting(
category="HARM_CATEGORY_SEXUALLY_EXPLICIT",
threshold="BLOCK_NONE"
),
types.SafetySetting(
category="HARM_CATEGORY_DANGEROUS_CONTENT",
threshold="BLOCK_NONE"
),
]
Método 2: Adicionar detalhes específicos ao comando
Comandos vagos são mais propensos a disparar filtros de segurança. Adicionar detalhes específicos pode guiar o modelo a gerar imagens mais "seguras":
❌ "Uma mulher"
→ O modelo pode gerar conteúdo interpretado pelo filtro como inadequado
✅ "Uma mulher vestindo um terno profissional, trabalhando em um escritório moderno,
luz natural, estilo de ilustração digital"
→ Cenário específico + descrição de vestimenta + estilo artístico → Taxa de sucesso muito maior
Métodos 3 a 8: Estratégias de otimização avançada
| Método | Ação | Efeito esperado |
|---|---|---|
| Método 3: Adicionar estilo artístico | Adicionar "digital illustration style" ou "watercolor style" ao final | Reduz o realismo → reduz gatilhos |
| Método 4: Especificar contexto do ambiente | Adicionar descrições claras ("no parque", "no escritório") | Limita o espaço de criação do modelo |
| Método 5: Evitar descrições de pele exposta | Usar "formal attire" ou "winter clothing" em vez de descrições vagas | Evita áreas sensíveis |
| Método 6: Usar comandos em inglês | O filtro de segurança em inglês é mais calibrado que em outros idiomas | Reduz bloqueios falsos |
| Método 7: Tentar novamente com outras palavras | Reescrever o comando automaticamente após uma falha | Aumenta a taxa de sucesso geral |
| Método 8: Invocar via APIYI | A APIYI possui configurações otimizadas para parâmetros de segurança | Taxa de sucesso geral superior |
Comparação de comandos antes e depois da otimização
| Cenário | Antes (baixa taxa) | Depois (alta taxa) |
|---|---|---|
| Pessoas | "Uma garota de biquíni" | "Uma mulher com roupas esportivas treinando na academia, estilo ilustração digital" |
| Alimentos | "Bife" | "Um bife ao ponto em um prato de cerâmica branco, mesa de restaurante, fotografia profissional de alimentos" |
| Animais | "Um cachorro" | "Um golden retriever pegando um frisbee no quintal, luz do sol da tarde, estilo ilustração digital" |
| E-commerce | "Modelo de lingerie" | "Foto de produto de um top esportivo branco, fundo branco puro, sem modelo, fotografia de produto" |
🎯 Princípio fundamental: Quanto mais específico for o comando = menos espaço para o modelo improvisar = menos chances de disparar filtros de segurança. Adicionar marcadores de estilo artístico (como "digital illustration") pode reduzir ainda mais os bloqueios relacionados ao realismo.
A taxa de sucesso via APIYI (apiyi.com) costuma ser maior do que a conexão direta com a API do Google, pois a plataforma otimizou as configurações de segurança.
Perguntas Frequentes
Q1: Por que o mesmo comando às vezes funciona e outras vezes é bloqueado?
Porque a segunda camada de filtragem de segurança verifica a imagem gerada, não o comando. Com o mesmo comando, a imagem gerada pelo modelo varia ligeiramente a cada vez (devido à aleatoriedade dos modelos de difusão), e certos resultados podem acabar atingindo o limite do filtro de segurança. Por isso, tentar novamente com o mesmo comando pode funcionar — o modelo pode acabar gerando uma imagem "mais segura".
Q2: É normal que thoughtsTokenCount seja maior que 0, mas candidatesTokenCount seja 0?
Sim, é normal. Isso indica precisamente que o bloqueio ocorreu na segunda camada (saída): o modelo concluiu o pensamento (Thinking) e gerou a imagem, mas ela foi bloqueada pelo filtro de segurança antes da entrega final. Os tokens de pensamento foram consumidos (173), mas como a imagem não foi efetivamente entregue, os tokens de saída são contados como 0. Este é um padrão de resposta específico do IMAGE_SAFETY — diferente do bloqueio na primeira camada (onde o thoughtsTokenCount também seria 0).
Q3: O que fazer com imagens de moda íntima/roupas de banho que são bloqueadas frequentemente?
Este é um cenário conhecido de bloqueio falso positivo frequente. Existem muitos relatos nos fóruns de desenvolvedores do Google sobre "imagens de e-commerce de moda íntima não-NSFW com erro IMAGE_SAFETY". Sugestões: 1) Use fotos de produtos em superfície plana (sem modelos) em vez de fotos com modelos; 2) Especifique claramente no comando "product flat lay, no model, white background"; 3) Utilize a APIYI (apiyi.com), pois as configurações de parâmetros de segurança da plataforma são otimizadas para cenários de e-commerce.
Q4: As solicitações bloqueadas são cobradas na APIYI?
Não. A APIYI garante que não há cobrança em caso de falha na geração, incluindo situações de bloqueio por IMAGE_SAFETY. Você paga apenas pelas imagens geradas com sucesso. Isso está alinhado com a lógica de cobrança da API oficial do Google (imagens bloqueadas não são cobradas), mas a APIYI oferece uma garantia adicional — mesmo os custos mínimos de tokens de entrada não são gerados.
Resumo
Pontos principais sobre o erro IMAGE_SAFETY no Nano Banana Pro:
- A essência do erro é a filtragem de saída da segunda camada: Seu comando passou pela primeira camada, o modelo concluiu o pensamento (173 tokens) e a imagem foi gerada — mas foi bloqueada pelo filtro de segurança de segunda camada, que não pode ser desativado, no momento da entrega final.
- Solicitações bloqueadas basicamente não são cobradas:
candidatesTokenCount: 0significa que os tokens de saída não são contabilizados. O Google afirma explicitamente que "não cobra por imagens bloqueadas", e ao utilizar a APIYI, você tem a garantia adicional de que não haverá cobrança em caso de falha. - A otimização do comando pode aumentar a taxa de sucesso para 70-80%: O princípio fundamental é "quanto mais específico, mais seguro" — adicione cenários detalhados, estilos artísticos, descrições de vestuário e utilize comandos em inglês.
Recomendamos utilizar o Nano Banana Pro através da APIYI (apiyi.com) — com configurações de segurança otimizadas, sem cobrança em caso de falha e 28% de desconto, reduzindo o impacto dos bloqueios falsos positivos do IMAGE_SAFETY no seu negócio.
📚 Referências
-
Documentação das Configurações de Segurança da API Gemini: Explicação oficial dos parâmetros de segurança
- Link:
ai.google.dev/gemini-api/docs/safety-settings - Descrição: Contém a configuração BLOCK_NONE e a lista de categorias de segurança
- Link:
-
Guia Completo de Correção de IMAGE_SAFETY para Nano Banana Pro: 8 métodos para aumentar a taxa de sucesso
- Link:
help.apiyi.com/en/nano-banana-pro-image-safety-error-fix-guide-en.html - Descrição: Inclui modelos de otimização de comando e soluções baseadas em cenários
- Link:
-
Discussão sobre IMAGE_SAFETY no Fórum de Desenvolvedores Google AI: Relatos da comunidade e respostas oficiais
- Link:
discuss.ai.google.dev/t/nano-banana-is-unusable-because-of-the-new-safety-filters/132366 - Descrição: O Google reconhece que os filtros estão "excessivamente cautelosos"
- Link:
-
Central de Documentação APIYI: Garantia de não cobrança em caso de falha no Nano Banana Pro
- Link:
docs.apiyi.com - Descrição: Contém otimização de parâmetros de segurança e guias de configuração para cenários de e-commerce
- Link:
Autor: Equipe Técnica APIYI
Troca de conhecimento: Sinta-se à vontade para discutir na seção de comentários. Para mais materiais, visite a central de documentação da APIYI em docs.apiyi.com
