title: "Guía técnica: Cómo interpretar y resolver el error IMAGE_SAFETY en Nano Banana Pro API"
description: "Analizamos el error IMAGE_SAFETY en Nano Banana Pro API: desglosamos el filtrado de seguridad, la facturación de tokens y estrategias para optimizar tus prompts."
Nota del autor: Análisis detallado campo a campo del error IMAGE_SAFETY en la API de Nano Banana Pro, examinando el mecanismo de filtrado de seguridad de doble capa, la lógica de facturación de tokens y 8 métodos prácticos para mejorar la tasa de éxito en la generación.
Al usar la API de Nano Banana Pro para la generación de imágenes, es posible que te hayas topado con esta respuesta desconcertante: aunque tu indicación no contenga nada sensible, recibes un finishReason: IMAGE_SAFETY, lo que significa que la imagen ha sido bloqueada por el filtro de seguridad. Lo más frustrante es que el campo thoughtsTokenCount: 173 en la respuesta indica que el modelo completó su proceso de razonamiento, pero la imagen fue "ejecutada" al final. En este artículo, analizaremos este error campo a campo, explicaremos el mecanismo de filtrado de doble capa de Google, la lógica de facturación de tokens cuando ocurre un bloqueo y cómo aumentar tu tasa de éxito.
Valor central: Al terminar de leer, entenderás el significado de cada campo en el error IMAGE_SAFETY, sabrás si se te cobran tokens cuando ocurre un bloqueo y cómo optimizar tus indicaciones para elevar la tasa de éxito al 70-80%.
Análisis detallado del error IMAGE_SAFETY
Primero, aclaremos qué significa cada campo en esta respuesta.
| Campo | Valor | Significado |
|---|---|---|
content.parts |
null |
No se devolvió ningún contenido (la imagen fue bloqueada) |
finishReason |
IMAGE_SAFETY |
Se activó el filtro de seguridad de salida de segunda capa |
finishMessage |
"Unable to show…" | Aviso oficial de Google: se violó la política de uso de IA generativa |
promptTokenCount |
276 | La entrada consumió 276 tokens |
candidatesTokenCount |
0 | Salida de 0 tokens (la imagen fue bloqueada, no hubo generación) |
totalTokenCount |
449 | Total de 449 tokens (276 de entrada + 173 de razonamiento) |
thoughtsTokenCount |
173 | El proceso de razonamiento del modelo consumió 173 tokens |
promptTokensDetails |
TEXT:18, IMAGE:258 | 18 tokens de texto + 258 tokens de imagen (imagen de referencia) |
modelVersion |
gemini-3-pro-image-preview | Modelo Nano Banana Pro |
Las 3 señales clave del error IMAGE_SAFETY
Señal 1: thoughtsTokenCount: 173 — El modelo realmente razonó
Esto indica que tu indicación superó la primera capa de seguridad (entrada), el modelo comenzó su proceso de razonamiento (Thinking) e incluso llegó a generar la imagen, pero fue interceptado por el filtro de seguridad de segunda capa justo antes de la salida final. El problema no está en tu indicación, sino en el contenido que el modelo "intentó dibujar".
Señal 2: candidatesTokenCount: 0 — Salida cero
Tras el bloqueo de la imagen, los tokens de salida se contabilizan como 0. Según la política oficial de Google, "no se le cobrará por las imágenes bloqueadas". Sin embargo, ten en cuenta que si los tokens de entrada (276) y los de razonamiento (173) se facturan o no, dependerá de la lógica de facturación específica.
Señal 3: IMAGE: 258 — Incluiste una imagen de referencia
Tu solicitud contiene una imagen de referencia (que consume 258 tokens de imagen). Esto significa que probablemente estés realizando una edición de imagen a imagen, no una generación desde texto puro. El filtrado de seguridad en escenarios de edición suele ser más estricto que en texto, ya que la imagen de referencia también es sometida a inspección.
El mecanismo de filtrado de seguridad de doble capa de Google
La clave para entender el error IMAGE_SAFETY es comprender que el filtrado de seguridad de Google no es único, sino de dos capas, y la segunda no se puede desactivar.
Primera capa: Configuración de seguridad de entrada (configurable)
| Dimensión | Descripción | ¿Configurable? |
|---|---|---|
| Ubicación | Entrada (indicación) | Sí |
| Objeto | Texto e imágenes enviados por el usuario | Sí |
| Configuración | BLOCK_NONE (sin bloqueo) | Sí |
| Resultado al activar | Solicitud rechazada, no consume tokens | — |
Puedes ajustar los safety_settings de la API a BLOCK_NONE para reducir la sensibilidad de esta primera capa.
Segunda capa: Filtrado de seguridad de salida (no configurable)
| Dimensión | Descripción | ¿Configurable? |
|---|---|---|
| Ubicación | Salida (imagen generada) | No |
| Objeto | Contenido de la imagen generada por el modelo | No |
| ¿Se puede desactivar? | No, obligatorio para todos los usuarios y niveles | No |
| Resultado al activar | finishReason: IMAGE_SAFETY, parts: null |
— |
El error IMAGE_SAFETY ocurre cuando se activa esta segunda capa. Tu indicación pasó la primera, el modelo terminó de razonar (173 tokens) y generó la imagen, pero fue bloqueada antes de la entrega final.
Google ha reconocido que este filtro "se ha vuelto más cauteloso de lo previsto", provocando muchos falsos positivos; incluso indicaciones tan inofensivas como "un perro" o "un tazón de avena" pueden ser bloqueadas.
¿Se cobra cuando IMAGE_SAFETY bloquea una solicitud?
Esta es la duda que más preocupa a los desarrolladores.
Reglas de facturación de IMAGE_SAFETY en Nano Banana Pro
| Concepto de facturación | ¿Se cobra si hay bloqueo? | Explicación |
|---|---|---|
| Costo de generación de imagen | No se cobra | Google especifica claramente: "You will not be charged for blocked images" |
| Tokens de salida | No se cobra | candidatesTokenCount: 0, si no hay salida, no hay cobro |
| Tokens de entrada | Posible cobro (mínimo) | 276 Tokens × $0.25/M ≈ $0.00007 (despreciable) |
| Tokens de razonamiento | Depende de la lógica de cobro | 173 Tokens, la API de Gemini podría incluirlos en los candidatos |
Conclusión: Cuando ocurre un bloqueo por IMAGE_SAFETY, no se generan los costos principales (generación de imagen y tokens de salida). El costo de los tokens de entrada es ínfimo (menos de una diezmilésima de dólar), por lo que es prácticamente despreciable.
Garantía adicional de APIYI: Al realizar la invocación del modelo a través de APIYI (apiyi.com), no se te cobrará si la generación falla, incluyendo los casos de bloqueo por IMAGE_SAFETY. Solo pagas por las imágenes generadas con éxito.
8 formas de mejorar la tasa de éxito de IMAGE_SAFETY
Dado que la segunda capa de filtrado de seguridad no se puede desactivar, solo nos queda utilizar métodos indirectos para mejorar la tasa de éxito.
Método 1: Configurar BLOCK_NONE para desactivar la primera capa
Primero, asegúrate de que la primera capa no aplique bloqueos adicionales:
from google.genai import types
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: Añadir detalles específicos a la indicación
Las indicaciones vagas son más propensas a activar los filtros de seguridad. Añadir detalles específicos guía al modelo para generar imágenes más "seguras":
❌ "Una mujer"
→ El modelo podría generar contenido que el filtro considere inapropiado
✅ "Una mujer con traje profesional, trabajando en una oficina moderna,
luz natural, estilo de ilustración digital"
→ Escenario específico + descripción de vestimenta + estilo artístico → Aumenta drásticamente la tasa de éxito
Métodos 3 al 8: Estrategias de optimización avanzada
| Método | Acción | Efecto esperado |
|---|---|---|
| Método 3: Añadir estilo artístico | Añadir "digital illustration style" o "watercolor style" al final | Reduce el realismo → Menos activaciones |
| Método 4: Especificar contexto ambiental | Añadir descripciones claras ("en un parque", "en una oficina") | Limita el margen de interpretación del modelo |
| Método 5: Evitar descripciones de piel expuesta | Usar "formal attire" o "winter clothing" en lugar de descripciones vagas | Evita áreas sensibles |
| Método 6: Usar indicaciones en inglés | El filtrado de seguridad en inglés está mejor calibrado | Menos falsos positivos |
| Método 7: Reintento automático con otras palabras | Reescribir la indicación automáticamente tras un fallo | Mejora la tasa de éxito global |
| Método 8: Invocar vía APIYI | APIYI tiene configuraciones optimizadas para parámetros de seguridad | Mayor tasa de éxito general |
Comparativa de la indicación antes y después de la optimización
| Escenario | Antes (baja tasa de éxito) | Después (alta tasa de éxito) |
|---|---|---|
| Personas | "Una chica en traje de baño" | "Una mujer con ropa deportiva entrenando en el gimnasio, estilo ilustración digital" |
| Comida | "Filete" | "Un filete a término medio en un plato blanco, mesa de restaurante, fotografía profesional de alimentos" |
| Animales | "Un perro" | "Un golden retriever atrapando un frisbee en un patio suburbano, sol de tarde, estilo ilustración digital" |
| E-commerce | "Modelo de lencería" | "Imagen plana de producto de un sujetador deportivo blanco, fondo blanco puro, sin modelo, fotografía de producto" |
🎯 Principio fundamental: Cuanto más específica sea la indicación = menos margen de libertad para el modelo = menos activaciones del filtro de seguridad. Añadir etiquetas de estilo artístico (como "digital illustration") puede reducir aún más los bloqueos relacionados con el realismo.
La tasa de éxito al invocar a través de APIYI (apiyi.com) suele ser superior a la conexión directa con la API de Google, ya que la plataforma cuenta con configuraciones optimizadas para los parámetros de seguridad.
Preguntas frecuentes
Q1: ¿Por qué la misma indicación a veces tiene éxito y otras veces es bloqueada?
Porque el segundo nivel de filtrado de seguridad analiza la imagen generada, no la indicación. Con la misma indicación, la imagen que genera el modelo varía ligeramente cada vez (debido a la aleatoriedad de los modelos de difusión), y algunos resultados pueden activar accidentalmente el umbral del filtro de seguridad. Por eso, reintentar con la misma indicación a veces funciona: el modelo simplemente generó una imagen "más segura" por azar.
Q2: ¿Es normal que thoughtsTokenCount sea mayor que 0 pero candidatesTokenCount sea 0?
Es normal. Esto indica precisamente que el bloqueo ocurrió en el segundo nivel (en la salida): el modelo completó su proceso de pensamiento (Thinking) y generó la imagen, pero esta fue interceptada por el filtro de seguridad antes de la entrega final. Los tokens de pensamiento ya se consumieron (173), pero como la imagen no se entregó realmente, los tokens de salida se contabilizan como 0. Este es un patrón de respuesta característico de IMAGE_SAFETY, a diferencia del bloqueo de primer nivel (donde el thoughtsTokenCount también sería 0).
Q3: ¿Qué hacer si las imágenes de lencería/trajes de baño para comercio electrónico son bloqueadas frecuentemente?
Este es un escenario de falso positivo muy común. En los foros de desarrolladores de Google hay muchos reportes sobre "imágenes de comercio electrónico de ropa interior sin contenido NSFW que reciben el error IMAGE_SAFETY". Recomendaciones: 1) Utilizar fotos de producto plano (sin modelo) en lugar de fotos con modelo; 2) Especificar claramente en la indicación "product flat lay, no model, white background"; 3) Realizar la invocación del modelo a través de APIYI (apiyi.com), ya que la configuración de parámetros de seguridad de la plataforma está optimizada para escenarios de comercio electrónico.
Q4: ¿Se cobran las solicitudes bloqueadas en APIYI?
No. APIYI garantiza que no se cobra si la generación falla, incluyendo los casos de bloqueo por IMAGE_SAFETY. Solo pagas por las imágenes generadas con éxito. Esto es consistente con la lógica de facturación de la API oficial de Google (las imágenes bloqueadas no se cobran), pero APIYI ofrece una garantía adicional: ni siquiera se generan cargos por los pequeños costos de los tokens de entrada.
Resumen
Puntos clave sobre el error IMAGE_SAFETY en Nano Banana Pro:
- La esencia del error es un filtrado de salida de segundo nivel: Tu indicación superó el primer nivel, el modelo completó su pensamiento (173 tokens) y la imagen ya se había generado, pero fue bloqueada por el filtro de seguridad de segundo nivel, el cual no se puede desactivar.
- Los bloqueos generalmente no tienen costo:
candidatesTokenCount: 0significa que los tokens de salida no se facturan. Google especifica que "no se cobra por imágenes bloqueadas", y al usar APIYI cuentas con la garantía adicional de que no hay cobros por fallos. - La optimización de la indicación puede elevar la tasa de éxito al 70-80%: El principio fundamental es "cuanto más específico, más seguro": añade escenarios concretos, estilos artísticos, descripciones de vestimenta y utiliza indicaciones en inglés.
Te recomendamos realizar la invocación del modelo Nano Banana Pro a través de APIYI (apiyi.com) para beneficiarte de una configuración optimizada de parámetros de seguridad, garantía de no cobro por fallos y un 28% de descuento, reduciendo así el impacto de los falsos positivos de IMAGE_SAFETY en tu negocio.
📚 Referencias
-
Documentación de ajustes de seguridad de la API de Gemini: Explicación oficial de los parámetros de configuración de seguridad.
- Enlace:
ai.google.dev/gemini-api/docs/safety-settings - Descripción: Incluye la configuración BLOCK_NONE y la lista de categorías de seguridad.
- Enlace:
-
Guía completa de solución para IMAGE_SAFETY de Nano Banana Pro: 8 métodos para mejorar la tasa de éxito.
- Enlace:
help.apiyi.com/en/nano-banana-pro-image-safety-error-fix-guide-en.html - Descripción: Incluye plantillas de optimización de indicaciones y soluciones basadas en escenarios.
- Enlace:
-
Discusión sobre IMAGE_SAFETY en el foro de desarrolladores de Google AI: Reportes de la comunidad y respuestas oficiales.
- Enlace:
discuss.ai.google.dev/t/nano-banana-is-unusable-because-of-the-new-safety-filters/132366 - Descripción: Google reconoce que los filtros son "demasiado cautelosos".
- Enlace:
-
Centro de documentación de APIYI: Garantía de no cobro por fallos en Nano Banana Pro.
- Enlace:
docs.apiyi.com - Descripción: Incluye optimización de parámetros de seguridad y guías de configuración para escenarios de comercio electrónico.
- Enlace:
Autor: Equipo técnico de APIYI
Intercambio técnico: Te invitamos a participar en la sección de comentarios; para más información, visita el centro de documentación de APIYI en docs.apiyi.com.
