|

Solución completa de errores Unsupported file URI type en Nano Banana Pro: 5 causas principales y plan de reparación integral

PorAPIYI - Stable and affordable AI API

Recientemente, un cliente que utilizaba Nano Banana Pro (ID del modelo: gemini-3-pro-image-preview) para realizar tareas de imagen a imagen se encontró con un error 400 muy al "estilo Google":

{
  "status_code": 400,
  "error": {
    "message": "Unsupported file URI type: {{ $json.imageUrls }}. File URI must be a File API (e.g. https://generativelanguage.googleapis.com/files/<id>), Youtube (e.g. https://www.youtube.com/watch?v=<id>), or HTTPS (e.g. http://path/to/file).), or a valid gURI (e.g. gs://bucket/object",
    "type": "",
    "code": 400
  }
}

El mensaje de error de Nano Banana Pro ya nos señala al "culpable": Unsupported file URI type: {{ $json.imageUrls }}. Fíjate que {{ $json.imageUrls }} es la variable de plantilla de n8n sin reemplazar; es decir, el cliente escribió una expresión dinámica en su flujo de trabajo, pero el motor nunca la renderizó como una URL real, enviándola literalmente como una cadena de texto al campo fileUri de la API de Gemini. Como Google no puede reconocer una URI que parece un {{ ... }}, rechaza la solicitud de inmediato.

Basándome en este error real y en los requisitos de formato de entrada de la documentación oficial de Google para gemini-3-pro-image-preview, he desglosado los 5 escenarios más comunes, proporcionando el código mínimo reproducible y la solución definitiva para cada uno. Después de leer esto, deberías ser capaz de localizar y corregir cualquier solicitud fallida con el error Unsupported file URI type en menos de 5 minutos.

nano-banana-pro-unsupported-file-uri-type-error-fix-es 图示

Resumen de la información clave del error de Nano Banana Pro

Antes de ponernos manos a la obra con el código, vamos a resumir los puntos críticos del error y los formatos de URI permitidos oficialmente en una sola tabla.

Dimensión Hecho clave
ID del modelo gemini-3-pro-image-preview (nombre oficial de Nano Banana Pro en la API de Gemini)
Estado HTTP del error 400 (Bad Request, error en los parámetros del cliente)
Campo clave del error Unsupported file URI type
Ubicación real del problema Campo fileData.fileUri en el cuerpo de la solicitud
Literal que aparece en el error {{ $json.imageUrls }} (expresión de n8n no renderizada)
Tipos de URI aceptados por Gemini URI de File API / URL de YouTube / URL HTTPS pública / URI gs:// de GCS
Formatos de imagen aceptados JPEG, JPG, PNG, WEBP, HEIF
¿Nano Banana Pro admite URL externas? ✅ Sí (los modelos Gemini 2.5+ admiten nativamente HTTPS público / URL prefirmadas)
Causa raíz más probable Variables de plantilla no reemplazadas en flujos de trabajo low-code como n8n / Make / Zapier

🎯 Consejo de diagnóstico rápido: Si tu cliente no quiere mostrarte el cuerpo completo de la solicitud, pídele que realice una llamada exitosa en el panel de control de APIYI (apiyi.com) usando el mismo modelo gemini-3-pro-image-preview y la misma imagen de referencia. Luego, compara el cuerpo de la solicitud fallida con la exitosa; es la forma más rápida de identificar el error de Nano Banana Pro.

Las 5 causas principales del error "Unsupported file URI type" en Nano Banana Pro

Tras clasificar los casos reales, hemos reducido el error Unsupported file URI type a 5 causas típicas. Las ordenamos de mayor a menor frecuencia de aparición.

Causa 1: Las variables de plantilla en n8n / Make / Zapier no se renderizaron

Este es el principal sospechoso de este error. {{ $json.imageUrls }} es la sintaxis de expresiones de n8n; en condiciones normales, debería reemplazarse antes de la ejecución por la URL real generada por el nodo anterior, por ejemplo https://cdn.example.com/uploads/abc.jpg. Sin embargo, hay situaciones típicas donde este reemplazo falla:

  1. El campo Body del nodo HTTP Request no está en modo "Expression", sino en modo "Fixed", lo que provoca que todo el JSON se envíe como una cadena de texto plano.
  2. El cuerpo JSON utiliza comillas dobles anidadas, lo que hace que n8n crea erróneamente que la expresión es parte del contenido de la cadena y omita su renderización.
  3. La estructura de salida del nodo anterior no coincide con la ruta escrita; por ejemplo, si el nodo anterior realmente genera imageUrl (singular) y tú escribiste $json.imageUrls (plural), el análisis falla y n8n devuelve la expresión original.
  4. Las expresiones en sub-nodos no iteran según el elemento, sino que toman el primero de forma fija, lo que en ciertas entradas resulta en undefined, convirtiéndose en el texto original tras la serialización.

Cómo identificarlo: Si ves que el error de Gemini contiene {{ ... }}, es 100% seguro que se trata de este problema, ya que una URL válida nunca tendría ese formato.

Causa 2: Error tipográfico en el nombre del campo, resultando en undefined / null

Justo después, tenemos los problemas con los nombres de los campos. Es muy probable que el código del cliente tenga algo así:

// El campo real devuelto por la interfaz upstream se llama imageUrl (singular)
const upstream = { imageUrl: "https://cdn.example.com/a.jpg" };

// Pero el downstream escribió imageUrls (plural, con s)
fileUri: upstream.imageUrls   // El resultado es undefined

Cuando undefined se serializa en JSON o se concatena en una cadena, se convierte en el texto "undefined". Gemini tampoco puede reconocer esto y lanza un error 400 casi idéntico al de la plantilla no renderizada. La diferencia es que el literal que aparece en el error es undefined en lugar de {{ ... }}.

Causa 3: Pasar un array como si fuera una cadena en fileUri

Esta tercera causa aparece a menudo en escenarios de "procesamiento por lotes de múltiples imágenes". El campo fileData.fileUri de la API de Gemini solo acepta una cadena individual, no un array. Sin embargo, muchos desarrolladores escriben esto:

// ❌ Error: insertar un array directamente en fileUri
{
  "fileData": {
    "fileUri": ["https://cdn.example.com/a.jpg", "https://cdn.example.com/b.jpg"],
    "mimeType": "image/jpeg"
  }
}

Tras la serialización JSON, este campo fileUri se convierte en la cadena ["https://...", "https://..."], Gemini falla al analizarlo y lanza directamente Unsupported file URI type. La forma correcta es generar un elemento parts independiente para cada imagen en lugar de meter un array en un único fileUri.

Causa 4: El protocolo de la URL o el formato de ruta no es compatible

El cuarto problema pertenece a la "desviación de formato". La API de Gemini solo acepta 4 tipos de URI; cualquier formato fuera de este rango activará el mismo error:

Tipo de URI Ejemplo ¿Aceptado por gemini-3-pro-image-preview?
Ruta File API https://generativelanguage.googleapis.com/files/abc123 ✅
URL de YouTube https://www.youtube.com/watch?v=xxxxx ✅(Principalmente para comprensión de video)
URL HTTPS pública https://cdn.example.com/img.jpg ✅(Soporte nativo desde Gemini 2.5+)
URI GCS gs:// gs://my-bucket/img.jpg ✅(Ruta de Vertex AI)
http:// plano http://cdn.example.com/img.jpg ⚠️ Rechazado en algunos casos, se recomienda actualizar a HTTPS
Ruta local file:// file:///Users/me/a.jpg ❌
data:image/...;base64, dataURL en base64 ❌(Debe colocarse en inlineData)
URL S3 pre-firmada https://bucket.s3.amazonaws.com/...?X-Amz-... ✅
URL SAS de Azure https://account.blob.core.windows.net/...?sv=... ✅

Si insertas una ruta de archivo local, un data: en base64 o una URL de intranet privada en fileUri, activarás sin excepción el error de Nano Banana Pro.

Causa 5: La URL es accesible pero requiere autenticación / no devuelve una imagen

La última categoría es "la URL parece correcta, pero Gemini no puede obtener el contenido". Casos comunes:

  • El enlace de OSS privado / Qiniu / Cloudinary no tiene permisos públicos, Gemini recibe un 403.
  • La URL de firma temporal ha caducado.
  • La URL no devuelve una imagen, sino una página HTML (por ejemplo, la "página de compartir" de algún servicio de alojamiento de imágenes, no el enlace directo).
  • La URL redirige a una página de inicio de sesión.
  • El tipo MIME no coincide con el campo mimeType.

Este tipo de problema a veces se lanza como Unsupported file URI type, y otras veces como 400 Invalid or unsupported file uri. La solución para ambos es la misma: accede a la URL directamente desde una ventana de incógnito del navegador para ver si puedes descargar una imagen válida; es el método más sencillo y efectivo.

nano-banana-pro-unsupported-file-uri-type-error-fix-es 图示

Reproducción mínima y solución única para el error de Nano Banana Pro

Tras analizar las 5 causas principales, a continuación presento el código de reproducción mínima + la versión corregida para cada escenario, que puedes copiar directamente en tu flujo de trabajo o backend para reemplazar el código actual.

Corrección 1: Pasar correctamente el parámetro imageUrls en n8n

Si el cliente se encuentra con este error de Nano Banana Pro y está utilizando el nodo HTTP Request de n8n, la forma correcta de escribirlo es la siguiente:

Configuración del nodo HTTP Request:

  • Method: POST
  • URL: https://api.apiyi.com/v1/messages (reemplaza con tu dirección de servicio proxy de API de APIYI)
  • Authentication: Header Auth (coloca tu clave API)
  • Body Content Type: JSON
  • Specify Body: Selecciona Using JSON (en lugar de Using Fields)
  • JSON Body (ten en cuenta que toda la sección JSON debe estar en modo expresión, es decir, el botón morado "fx" a la izquierda debe estar activado):
={
  "model": "gemini-3-pro-image-preview",
  "contents": [
    {
      "parts": [
        { "text": "Convierte esta imagen al estilo de Hayao Miyazaki" },
        {
          "fileData": {
            "fileUri": "{{ $json.imageUrls }}",
            "mimeType": "image/jpeg"
          }
        }
      ]
    }
  ]
}

Hay 3 puntos clave:

  1. La cadena JSON debe comenzar con el signo =, lo que indica a n8n que todo el bloque es una expresión que debe ser evaluada;
  2. "{{ $json.imageUrls }}" debe estar entre comillas dobles, para que el contenido interno {{ }} sea reemplazado por la cadena real;
  3. El nodo anterior debe emitir realmente un campo llamado imageUrls; si emite imageUrl (singular) o image_url, debes ajustar el nombre del campo en consecuencia.

Si se cumplen estos 3 puntos, el error Unsupported file URI type desaparecerá de inmediato.

Corrección 2: Evitar errores tipográficos en los nombres de campos en Python / Node.js

Si el cliente utiliza código backend, recomiendo añadir una validación de entrada para detectar errores tipográficos antes de enviar la solicitud a Gemini:

import requests

def call_nano_banana_pro(prompt: str, image_url: str):
    # Validación defensiva: intercepta valores None, cadenas vacías o plantillas sin renderizar antes de enviar
    if not image_url or not isinstance(image_url, str):
        raise ValueError(f"image_url debe ser una cadena no vacía, valor actual: {image_url!r}")
    if image_url.startswith("{{") or "undefined" in image_url:
        raise ValueError(f"image_url parece ser una variable de plantilla sin renderizar: {image_url}")
    if not image_url.startswith(("https://", "gs://")):
        raise ValueError(f"image_url debe comenzar con https:// o gs://: {image_url}")

    payload = {
        "model": "gemini-3-pro-image-preview",
        "contents": [{
            "parts": [
                {"text": prompt},
                {"fileData": {
                    "fileUri": image_url,
                    "mimeType": "image/jpeg"
                }}
            ]
        }]
    }

    resp = requests.post(
        "https://api.apiyi.com/v1/messages",
        headers={"Authorization": "Bearer TU_CLAVE_API"},
        json=payload,
        timeout=120
    )
    return resp.json()

Este enfoque de "validar antes de enviar" puede interceptar el 90% de los errores de Nano Banana Pro antes de la invocación del modelo, evitando ensuciar los registros de fallos de Gemini.

Corrección 3: Dividir correctamente las imágenes en múltiples parts

Si realmente necesitas enviar varias imágenes de referencia a Nano Banana Pro (por ejemplo, para transferencia de estilo + consistencia facial), la forma correcta es crear elementos parts independientes para cada imagen, en lugar de insertar un array en fileUri:

// ✅ Forma correcta
const imageUrls = [
  "https://cdn.example.com/style.jpg",
  "https://cdn.example.com/person.jpg"
];

const payload = {
  model: "gemini-3-pro-image-preview",
  contents: [{
    parts: [
      { text: "Dibuja al personaje de la segunda imagen con el estilo de la primera" },
      ...imageUrls.map(url => ({
        fileData: { fileUri: url, mimeType: "image/jpeg" }
      }))
    ]
  }]
};

const resp = await fetch("https://api.apiyi.com/v1/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer TU_CLAVE_API"
  },
  body: JSON.stringify(payload)
});

Esta estructura no solo evita el error Unsupported file URI type, sino que permite a Gemini comprender correctamente la relación semántica entre las imágenes.

Corrección 4: Volver a base64 inline si la URL no es accesible

Si la URL que obtienes pertenece a un bucket privado, una red interna o es una URL temporal, es posible que el servidor de Gemini no pueda acceder a ella. La alternativa más robusta es usar inlineData + base64:

import base64
import requests

def call_with_base64(prompt: str, local_path: str):
    with open(local_path, "rb") as f:
        b64 = base64.b64encode(f.read()).decode("utf-8")

    payload = {
        "model": "gemini-3-pro-image-preview",
        "contents": [{
            "parts": [
                {"text": prompt},
                {"inlineData": {
                    "mimeType": "image/jpeg",
                    "data": b64
                }}
            ]
        }]
    }

    return requests.post(
        "https://api.apiyi.com/v1/messages",
        headers={"Authorization": "Bearer TU_CLAVE_API"},
        json=payload
    ).json()

Nota: inlineData utiliza el campo data (base64 puro, sin el prefijo data:image/jpeg;base64,), mientras que fileData utiliza el campo fileUri. Ambos son excluyentes, no los utilices juntos.

🎯 Recomendación de estabilidad: Para escenarios donde el origen de la URL no es controlable (por ejemplo, subidas de clientes o interfaces de terceros), recomendamos que la imagen a imagen utilice por defecto base64 inline y se realice la invocación a gemini-3-pro-image-preview a través de una plataforma de servicio proxy de API como APIYI (apiyi.com), evitando que Gemini rechace URLs externas por problemas de red o permisos.

Lista de verificación para el error de Nano Banana Pro

He condensado todo lo anterior en una lista de "verificación de 5 minutos". Cuando un cliente encuentre el error Unsupported file URI type, puede seguir estos pasos directamente.

Lista de verificación de 5 minutos

Paso Acción Resultado esperado
1 Copia el literal que aparece después de Unsupported file URI type: en el mensaje de error Obtener el valor real de fileUri recibido por Gemini
2 Comprueba si este valor contiene {{, undefined, null, [ Si es así → 90% es una plantilla no renderizada o error de nombre de campo
3 Abre esta URL directamente en una ventana de incógnito del navegador Esperado: poder descargar una imagen JPEG/PNG/WEBP válida
4 Verifica si el protocolo de la URL es https:// o gs:// Si no lo es → Cambia el protocolo o usa base64
5 Comprueba si es un bucket privado, una firma expirada o una redirección Si es así → Cambia a una URL pública o usa base64
6 Prueba en el panel de control de APIYI (apiyi.com) con el mismo modelo y una imagen pública conocida Si funciona → El problema está en el cliente; si falla → Infórmanos

Siguiendo estos 6 pasos, prácticamente no habrá ningún error de Nano Banana Pro cuya causa raíz no pueda ser identificada.

Preguntas frecuentes (FAQ) sobre el error "Unsupported file URI type" en Nano Banana Pro

P1: ¿Por qué el mensaje de error muestra literalmente la cadena {{ $json.imageUrls }}?

Porque cuando la API de Gemini recibe la solicitud, escribe el valor del campo fileUri tal cual en el mensaje de error; este es el comportamiento estándar de Google y su objetivo es ayudarte a localizar rápidamente "qué es exactamente lo que estoy enviando". Si ves una cadena que parece {{ ... }}, significa que la variable de plantilla del flujo de trabajo low-code no se ha renderizado; si ves undefined o null, es un error tipográfico en el nombre del campo. Te sugiero que primero realices una invocación exitosa en APIYI (apiyi.com) usando una URL pública fija y luego alinees tu cliente con ese cuerpo de solicitud exitoso.

P2: ¿Qué URLs admite realmente Nano Banana Pro / gemini-3-pro-image-preview?

Según la documentación oficial de Google, fileUri acepta 4 tipos de URI: rutas de File API (https://generativelanguage.googleapis.com/files/...), URLs de YouTube (principalmente para comprensión de video), URLs HTTPS públicas (incluyendo S3 Pre-signed y Azure SAS) y URIs de GCS (gs://). Los modelos Gemini 2.5 y superiores admiten de forma nativa HTTPS público, por lo que gemini-3-pro-image-preview no requiere que subas la imagen a la File API antes de realizar la invocación.

P3: ¿Qué hago si {{ $json.imageUrls }} no se renderiza en n8n?

Hay 3 puntos de verificación clave: primero, el cuerpo JSON del nodo HTTP Request debe tener activado el modo de expresión (debe haber un signo = antes del bloque JSON o el botón "fx" a la izquierda debe estar iluminado); segundo, la ruta del campo debe coincidir con la salida real del nodo anterior (puedes verificar el nombre del campo en el panel "Output" después de ejecutar el nodo en n8n); tercero, si usas un sub-nodo, la expresión toma por defecto solo el primer elemento; o bien cambias al nodo principal, o usas primero un nodo "Item Lists" para expandir los datos.

P4: ¿Cómo corrijo el error cuando aparece undefined?

Esto indica que estás intentando acceder a un campo inexistente en tu código. La corrección más rápida es añadir una aserción antes de llamar a Gemini: assert image_url is not None and isinstance(image_url, str); luego, verifica el valor de retorno de la interfaz upstream para confirmar el nombre del campo. Los errores tipográficos comunes incluyen imageUrls vs imageUrl, image_url vs imageUrl, o url vs uri. En entornos de producción, se recomienda —como en el código Python de la "Corrección 2" de este artículo— bloquear cualquier cadena que no sea https o gs antes de enviar la solicitud.

P5: ¿Puedo incluir varias imágenes directamente en fileUri?

No. fileUri solo acepta una cadena única. Si necesitas enviar varias imágenes, la forma correcta es crear un nuevo elemento { "fileData": { "fileUri": "...", "mimeType": "..." } } para cada imagen y colocarlos todos en el mismo array parts. Así es como Gemini puede identificar correctamente la relación semántica entre las imágenes.

P6: ¿Qué hago si las URLs de cubos privados o firmas temporales no pueden ser públicas?

La solución más robusta es usar inlineData + base64: lee la imagen desde tu lado, codifícala en base64 y colócala directamente en el cuerpo de la solicitud. De esta forma, no necesitas que el servidor de Gemini descargue recursos externos, evitando todos los problemas de "fallo de autenticación / firma caducada / MIME no coincidente". El costo es que el cuerpo de la solicitud será más grande, por lo que es ideal para escenarios de una sola imagen de tamaño pequeño. Si realizas una generación de imágenes de alta concurrencia, te recomendamos subir la imagen a un CDN accesible públicamente y luego invocar gemini-3-pro-image-preview a través de APIYI (apiyi.com). Esto evita el aumento de tamaño por base64 y facilita la gestión de caché y reintentos a nivel de plataforma.

nano-banana-pro-unsupported-file-uri-type-error-fix-es 图示

Resumen: Mejores prácticas tras corregir errores en Nano Banana Pro

Volviendo al error específico de Nano Banana Pro reportado por el cliente: Unsupported file URI type: {{ $json.imageUrls }}, podemos confirmar con total seguridad que no es un problema de Gemini, sino que n8n / el flujo de trabajo low-code no reemplazó la variable de plantilla por la URL real, provocando que la cadena {{ ... }} se enviara tal cual a la API de Gemini. El método de corrección ya se ha dado en la "Corrección 1" de este artículo: basta con activar el modo de expresión en el cuerpo JSON del nodo HTTP Request y confirmar que el nodo anterior realmente emitió el campo imageUrls.

En un nivel más amplio, el error Unsupported file URI type expone un problema muy común: muchos equipos carecen de una capa de "validación de entrada" al invocar APIs de imágenes, lo que provoca que, cuando Gemini rechaza la solicitud, sea imposible distinguir si se trata de un problema del modelo, de la red o de los parámetros. La lista de verificación de 5 minutos, el código de validación en Python y la sintaxis de expresiones de n8n proporcionados en este artículo pueden tomarse directamente como el procedimiento estándar de respuesta del equipo.

🎯 Recomendación final: Si estás construyendo un flujo de trabajo de imagen a imagen basado en gemini-3-pro-image-preview para clientes, te sugerimos centralizar todas las invocaciones de Nano Banana Pro a través de una plataforma de proxy de API como APIYI (apiyi.com). Esto permite reproducir rápidamente y comparar solicitudes fallidas en la consola, además de cambiar sin problemas a modelos de la misma categoría como Nano Banana 2 / Seedream en caso de fallos en Google, permitiendo que errores de parámetros como Unsupported file URI type sean localizados y corregidos de inmediato.

Autor: Equipo APIYI ｜ Enfocados en la implementación de Modelos de Lenguaje Grandes y la ingeniería de estabilidad. Para más casos prácticos de resolución de problemas con Gemini y APIs de imágenes, visita APIYI (apiyi.com).

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Publicaciones Similares