Solución de errores de Nano Banana
Los valores de los parámetros se describen en Texto a imagen y tamaño con Nano Banana.
Buscar por síntoma
400 Request contains an invalid argument
{
"error": {
"code": 400,
"message": "Request contains an invalid argument.",
"status": "INVALID_ARGUMENT"
}
}Este error no indica qué parámetro falla. En nuestras mediciones, todos los casos siguientes lo devuelven:
Cómo diagnosticarlo: primero, quite imageConfig y reintente; si la imagen se genera con normalidad, el problema está en la relación de aspecto o en la resolución. Después, vuelva a añadirlas una a una para localizarlo.
Relación de aspecto o resolución incorrectas
Compruebe primero el ancho y alto reales de la imagen de salida y, después, revise la tabla siguiente:
Forma correcta:
{
"contents": [{ "parts": [{ "text": "..." }] }],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": { "aspectRatio": "9:16", "imageSize": "2K" }
}
}Se reconocen ambas formas, imageConfig / image_config y aspectRatio / aspect_ratio; en nuestras mediciones, image_config: { aspect_ratio: "9:16" } produjo correctamente 768×1376.
La respuesta no contiene imagen
En clientes como Cherry Studio o LobeHub, añádalo como modelo de generación de imágenes, no como modelo de chat.
410 model_deprecated
{
"error": {
"message": "Model 'google/gemini-3-pro-image-preview' is deprecated and no longer accepts requests; please switch to an active model",
"type": "model_deprecated",
"code": 410
}
}Los ID antiguos terminados en -preview se han retirado; use los ID de la versión estable:
En la ruta del endpoint nativo, el ID del modelo puede llevar el prefijo google/ o no; en nuestras mediciones, ambas formas funcionan.
El resultado de la edición no tiene relación con la imagen original
Para confirmar que la imagen de referencia se leyó: en el endpoint nativo, compruebe si usageMetadata.promptTokensDetails contiene un elemento IMAGE; en el endpoint compatible con OpenAI, consulte usage.input_tokens_details.image_tokens. En nuestras mediciones, una imagen de referencia de 1024×1024 cuenta como 1.120 tokens.
Bloqueo de seguridad
Cuando la política de seguridad bloquea una petición, la respuesta no contiene imagen y el motivo figura en finishReason o en promptFeedback.blockReason. Significado de cada valor (según la definición oficial de Google):
El código no debe suponer que la respuesta siempre contiene una imagen: compruebe primero que existe candidates y que finishReason es STOP, y solo después lea inlineData. La definición de cada campo está en Gemini API · FinishReason .
Tiempo de espera agotado, 504, 524
La API es síncrona; en nuestras mediciones, 1K tarda entre 5 y 20 segundos y 4K unos 30 segundos, y en horas punta tarda más. El tiempo de espera predeterminado habitual de 60 segundos no basta.
- Configure el tiempo de espera del cliente en 300 segundos o más.
- Revise el tiempo de espera de los proxies intermedios como Nginx, Vercel o Cloudflare, cuyo valor predeterminado suele ser de solo 60 a 100 segundos.
- Un PNG en 4K ocupa unos 16 MB y el cuerpo de la respuesta supera los 20 MB; asegúrese de que el proxy no trunca respuestas de gran tamaño.
Si el cliente se desconecta antes de tiempo, la petición se factura igualmente.
Otros errores
Al contactar con el soporte técnico, incluya el request_id de la respuesta y el mensaje de error completo.
Preguntas frecuentes
¿Qué hago si Nano Banana devuelve Request contains an invalid argument?
Este error no indica qué parámetro falla; normalmente, la relación de aspecto o la resolución está fuera de lo que admite el modelo. Por ejemplo, 5:3 no es una relación admitida; Nano Banana 2 Lite solo tiene 1K; Pro no tiene 512; y el máximo de todos los modelos es 4K. Quite primero imageConfig y reintente; después, vuelva a añadir los valores uno a uno para localizar el problema.
¿Qué hago si configuro aspectRatio en Nano Banana y la relación de aspecto no es la correcta?
Compruebe primero que imageConfig está dentro de generationConfig y no en el nivel superior del cuerpo de la petición. Después, confirme que el modelo admite ese valor: Pro no admite 1:4, 4:1, 1:8 ni 8:1; y la generación anterior, Nano Banana, no admite imageSize.
¿Por qué no encuentro la imagen en la respuesta de Nano Banana?
La causa habitual es que el código solo lee el primer elemento de parts y la imagen va después; recorra parts y busque inlineData. Otra causa es que la política de seguridad haya bloqueado la petición; en ese caso, finishReason no es STOP.
¿Qué hago si gemini-3-pro-image-preview devuelve 410 model_deprecated?
Los ID de las versiones preview se han retirado. Sustituya google/gemini-3-pro-image-preview por google/gemini-3-pro-image, y google/gemini-3.1-flash-image-preview por google/gemini-3.1-flash-image.
¿Qué hago si Nano Banana devuelve IMAGE_SAFETY?
IMAGE_SAFETY indica que la política de seguridad consideró no permitida la imagen generada; reintentar sin cambios da el mismo resultado. Modifique el prompt evitando personas reales, personajes protegidos por derechos de autor o contenido sensible, y vuelva a intentarlo.
¿Por qué la imagen de referencia no surte efecto al editar con Nano Banana?
input_images es un campo de Qwen-Image y Gemini no lo admite. Suba el archivo a /v1/images/edits o, en el endpoint nativo de Gemini, coloque la imagen como inlineData en el mismo parts que el texto.