|

Полное руководство по устранению ошибки Unsupported file URI type в Nano Banana Pro: 5 основных причин и решение проблемы

ОтAPIYI - Stable and affordable AI API

Недавно один из наших клиентов при вызове Nano Banana Pro (ID модели: gemini-3-pro-image-preview) для генерации «изображение-в-изображение» столкнулся с типичной «гугловской» ошибкой 400:

{
  "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
  }
}

Текст этой ошибки Nano Banana Pro фактически сам указывает на «виновника»: Unsupported file URI type: {{ $json.imageUrls }}. Обратите внимание, что {{ $json.imageUrls }} — это необработанная переменная шаблона n8n. Иными словами, клиент прописал в рабочем процессе динамическое выражение, но движок не отрендерил его в реальный URL, а отправил в поле fileUri API Gemini как обычную строку. Google, разумеется, не смог распознать URI, выглядящий как {{ ... }}, и отклонил запрос.

Основываясь на этой реальной ошибке и официальной документации Google к модели gemini-3-pro-image-preview, мы разберем 5 самых частых сценариев возникновения проблемы и предложим готовые решения для каждого из них. После прочтения вы сможете находить и исправлять любую ошибку Unsupported file URI type менее чем за 5 минут.

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

Краткий обзор ключевой информации об ошибке Nano Banana Pro

Прежде чем переходить к коду, давайте сведем основные факты об ошибке и требования к формату URI в одну таблицу.

Параметр Факт
ID модели gemini-3-pro-image-preview (официальное название Nano Banana Pro в API Gemini)
HTTP-статус ошибки 400 (Bad Request, ошибка параметров клиента)
Ключевое поле ошибки Unsupported file URI type
Где именно проблема Поле fileData.fileUri в теле запроса
Что попало в ошибку {{ $json.imageUrls }} (необработанное выражение n8n)
Допустимые типы URI File API URI / YouTube URL / публичный HTTPS URL / GCS gs:// URI
Поддерживаемые форматы JPEG, JPG, PNG, WEBP, HEIF
Поддержка внешних URL? ✅ Да (модели Gemini 2.5+ нативно поддерживают публичные HTTPS / пре-сайн URL)
Вероятная причина Переменные шаблона в low-code инструментах (n8n, Make, Zapier) не были подставлены

🎯 Совет по быстрой диагностике: Если клиент не хочет показывать полный запрос, попросите его выполнить успешный вызов с той же моделью gemini-3-pro-image-preview и тем же эталонным изображением в консоли APIYI (apiyi.com), а затем сравните (diff) тело успешного и неудачного запросов. Это самый быстрый способ локализовать ошибку Nano Banana Pro.

5 основных причин ошибки Unsupported file URI type в Nano Banana Pro

После анализа реальных кейсов мы свели ошибку Unsupported file URI type к 5 типичным причинам. Расположим их в порядке убывания частоты возникновения.

Причина 1: Шаблонные переменные в n8n / Make / Zapier не были отрендерены

Это «подозреваемый номер один» для данной ошибки. {{ $json.imageUrls }} — это синтаксис выражений n8n, который в норме должен заменяться на реальный URL (например, https://cdn.example.com/uploads/abc.jpg) до выполнения запроса. Однако есть несколько ситуаций, когда эта подстановка не срабатывает:

  1. В узле HTTP Request для поля Body не выбран режим "Expression", а оставлен "Fixed". В итоге весь JSON отправляется как обычная текстовая строка.
  2. В JSON Body используется двойная вложенность кавычек, из-за чего n8n ошибочно принимает выражение за часть строкового содержимого и пропускает рендеринг.
  3. Структура вывода предыдущего узла не совпадает с путем, который вы прописали — например, на выходе imageUrl (единственное число), а вы указали $json.imageUrls (множественное). После ошибки парсинга n8n возвращает выражение «как есть».
  4. Выражение в Sub-node не итерируется по элементам, а жестко берет первый, что при определенных входных данных дает undefined, который при сериализации превращается в текст.

Как определить: Если в ошибке Gemini вы видите {{ ... }}, то это на 100% данная проблема, так как обычный URL не может содержать такие символы.

Причина 2: Опечатка в имени поля, из-за чего передается undefined / null

Следом идут ошибки в именах полей. В коде пользователя часто встречается такая ситуация:

// Входящий интерфейс на самом деле возвращает поле imageUrl (ед. число)
const upstream = { imageUrl: "https://cdn.example.com/a.jpg" };

// Но в коде написано imageUrls (мн. число, с буквой s)
fileUri: upstream.imageUrls   // Результат: undefined

При JSON-сериализации или конкатенации строк undefined превращается в строку "undefined". Gemini не может её распознать и выдает ошибку 400, почти идентичную ошибке нерендеренных шаблонов. Разница лишь в том, что в тексте ошибки будет undefined, а не {{ ... }}.

Причина 3: Передача массива вместо строки в fileUri

Эта проблема часто возникает при пакетной обработке нескольких изображений. Поле fileData.fileUri в API Gemini принимает только одну строку, а не массив. Но многие разработчики пишут так:

// ❌ Ошибка: передача массива напрямую в fileUri
{
  "fileData": {
    "fileUri": ["https://cdn.example.com/a.jpg", "https://cdn.example.com/b.jpg"],
    "mimeType": "image/jpeg"
  }
}

После сериализации JSON поле fileUri превращается в строку ["https://...", "https://..."], Gemini не может это распарсить и выдает Unsupported file URI type. Правильный подход — создавать отдельный элемент parts для каждого изображения, а не запихивать массив в один fileUri.

Причина 4: Неподдерживаемый протокол или формат пути

Четвертая проблема — «несоответствие форматов». API Gemini поддерживает только 4 типа URI. Любой другой вариант вызовет ошибку:

Тип URI Пример Поддерживается ли gemini-3-pro-image-preview
Путь File API https://generativelanguage.googleapis.com/files/abc123 ✅
YouTube URL https://www.youtube.com/watch?v=xxxxx ✅(для анализа видео)
Публичный HTTPS URL https://cdn.example.com/img.jpg ✅(нативно с Gemini 2.5+)
GCS gs:// URI gs://my-bucket/img.jpg ✅(путь Vertex AI)
http:// (открытый) http://cdn.example.com/img.jpg ⚠️ Иногда отклоняется, лучше HTTPS
file:// (локальный) file:///Users/me/a.jpg ❌
data:image/...;base64, base64 dataURL ❌(нужно использовать inlineData)
Pre-signed S3 URL https://bucket.s3.amazonaws.com/...?X-Amz-... ✅
Azure SAS URL https://account.blob.core.windows.net/...?sv=... ✅

Если вы вставите в fileUri путь к локальному файлу, base64-строку или ссылку на закрытую внутреннюю сеть, вы неизбежно получите ошибку Nano Banana Pro.

Причина 5: URL доступен, но требует авторизации или ведет не на картинку

Последняя категория — «URL выглядит правильно, но Gemini не может получить содержимое». Типичные случаи:

  • Ссылка на частное хранилище (OSS / Qiniu / Cloudinary) без публичного доступа — Gemini получает 403.
  • Срок действия временной ссылки истек.
  • URL ведет не на изображение, а на HTML-страницу (например, «страницу просмотра» фотохостинга вместо прямой ссылки).
  • Редирект URL на страницу логина.
  • MIME-тип не совпадает с полем mimeType.

Такие проблемы иногда тоже выдают Unsupported file URI type, а иногда — 400 Invalid or unsupported file uri. Метод исправления один: попробуйте открыть ссылку в режиме инкогнито в браузере и проверить, скачивается ли оттуда реальный файл изображения. Это самый простой и эффективный способ диагностики.

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

Минимальное воспроизведение и быстрое решение ошибок Nano Banana Pro

Разобравшись с 5 основными причинами ошибок, давайте перейдем к минимально воспроизводимому коду и исправленным версиям для каждого сценария. Вы можете просто скопировать их и заменить в своем рабочем процессе или бэкенде.

Исправление 1: Правильная передача параметра imageUrls в n8n

Если клиент столкнулся с ошибкой Nano Banana Pro при использовании узла HTTP Request в n8n, правильный вариант настройки выглядит так:

Конфигурация узла HTTP Request:

  • Method: POST
  • URL: https://api.apiyi.com/v1/messages (замените на ваш адрес прокси-сервера APIYI)
  • Authentication: Header Auth (укажите ваш API-ключ)
  • Body Content Type: JSON
  • Specify Body: выберите Using JSON (а не Using Fields)
  • JSON Body (обратите внимание: весь JSON должен быть в режиме выражения, фиолетовая кнопка fx слева должна быть активна):
={
  "model": "gemini-3-pro-image-preview",
  "contents": [
    {
      "parts": [
        { "text": "Преврати это изображение в стиле Хаяо Миядзаки" },
        {
          "fileData": {
            "fileUri": "{{ $json.imageUrls }}",
            "mimeType": "image/jpeg"
          }
        }
      ]
    }
  ]
}

Есть 3 ключевых момента:

  1. Перед JSON-строкой стоит знак =, который говорит n8n, что это выражение, которое нужно обработать;
  2. Внешние двойные кавычки вокруг "{{ $json.imageUrls }}" обязательны, чтобы внутренний {{ }} был заменен на реальную строку;
  3. Предыдущий узел должен действительно выводить поле с именем imageUrls. Если он выводит imageUrl (в единственном числе) или image_url, измените имя поля соответствующим образом.

Как только эти 3 условия будут выполнены, ошибка Unsupported file URI type исчезнет.

Исправление 2: Предотвращение опечаток в именах полей (Python / Node.js)

Если вы используете бэкенд-код, рекомендую добавить проверку входных данных, чтобы выявлять опечатки до отправки запроса в Gemini:

import requests

def call_nano_banana_pro(prompt: str, image_url: str):
    # Защитная проверка: отсекаем None / пустые строки / шаблоны до отправки
    if not image_url or not isinstance(image_url, str):
        raise ValueError(f"image_url должен быть непустой строкой, текущее значение: {image_url!r}")
    if image_url.startswith("{{") or "undefined" in image_url:
        raise ValueError(f"image_url выглядит как нерендеренная переменная шаблона: {image_url}")
    if not image_url.startswith(("https://", "gs://")):
        raise ValueError(f"image_url должен начинаться с https:// или 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 YOUR_API_KEY"},
        json=payload,
        timeout=120
    )
    return resp.json()

Такой подход "сначала проверка, потом отправка" позволяет перехватить 90% ошибок Nano Banana Pro до вызова API, не засоряя логи ошибок на стороне Gemini.

Исправление 3: Правильное разделение изображений на части (parts)

Если вам действительно нужно передать несколько эталонных изображений в Nano Banana Pro (например, для переноса стиля + фиксации лица), правильный способ — создать отдельные элементы parts для каждого изображения, а не вставлять массив в fileUri:

// ✅ Правильный вариант
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: "Нарисуй персонажа со второго изображения в стиле первого" },
      ...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 YOUR_API_KEY"
  },
  body: JSON.stringify(payload)
});

Этот метод не только предотвращает ошибку Unsupported file URI type, но и помогает Gemini правильно понять семантическую связь между изображениями.

Исправление 4: Использование base64 при недоступности URL

Если полученный вами URL ведет к приватному хранилищу, внутренней сети или является временным, сервер Gemini может не получить к нему доступ. Самый надежный вариант — перейти на 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 YOUR_API_KEY"},
        json=payload
    ).json()

Внимание: inlineData использует поле data (чистый base64, без префикса data:image/jpeg;base64,), а fileData использует поле fileUri. Они взаимоисключающие, не заполняйте оба одновременно.

🎯 Совет по стабильности: Для сценариев, где источник URL неконтролируем (например, загрузка пользователем или сторонний API), мы рекомендуем использовать изображение-в-изображение через base64 + вызов gemini-3-pro-image-preview через сервис-прокси APIYI (apiyi.com). Это поможет избежать проблем с сетью или доступом, из-за которых Gemini может периодически отклонять внешние URL.

Чек-лист для диагностики ошибок Nano Banana Pro

Мы сжали всё вышесказанное в "5-минутный чек-лист". Если клиент видит ошибку Unsupported file URI type, просто пройдитесь по этим пунктам.

5-минутный чек-лист

Шаг Действие Ожидаемый результат
1 Скопируйте значение после Unsupported file URI type: в сообщении об ошибке Получить фактическое значение fileUri, принятое Gemini
2 Проверьте, содержит ли это значение {{, undefined, null, [ Если да — в 90% случаев это нерендеренный шаблон или ошибка в имени поля
3 Откройте этот URL в режиме инкогнито в браузере Ожидание: скачивание корректного файла JPEG/PNG/WEBP
4 Проверьте, начинается ли протокол URL с https:// или gs:// Если нет — измените протокол или используйте base64
5 Проверьте, не является ли это приватным бакетом, просроченной подписью или редиректом Если да — используйте публичный URL или base64
6 Попробуйте воспроизвести ошибку в консоли APIYI (apiyi.com) с той же моделью и публичным изображением Если получилось — проблема в клиенте; если нет — сообщите нам

Выполнив эти 6 шагов, вы практически гарантированно найдете корень любой ошибки Nano Banana Pro.

FAQ по ошибкам типа Unsupported file URI в Nano Banana Pro

Q1: Почему в тексте ошибки буквально отображается {{ $json.imageUrls }}?

Потому что при получении запроса Gemini API вставляет значение поля fileUri прямо в сообщение об ошибке — это стандартное поведение Google, призванное помочь вам быстро понять, «что именно я туда отправил». Если вы видите литерал вида {{ ... }}, значит, переменная шаблона low-code рабочего процесса не была отрендерена. Если же там undefined или null, значит, допущена опечатка в названии поля. Рекомендую сначала воспроизвести успешный вызов на APIYI (apiyi.com), используя фиксированный публичный URL, а затем привести структуру запроса клиента в соответствие с этим рабочим телом запроса.

Q2: Какие URL на самом деле поддерживает Nano Banana Pro / gemini-3-pro-image-preview?

Согласно официальной документации Google, fileUri принимает 4 типа URI: пути File API (https://generativelanguage.googleapis.com/files/...), YouTube URL (в основном для анализа видео), публичные HTTPS URL (включая S3 Pre-signed и Azure SAS) и GCS gs:// URI. Модели Gemini 2.5 и новее поддерживают публичные HTTPS «из коробки», поэтому для gemini-3-pro-image-preview не нужно предварительно загружать изображение в File API перед вызовом.

Q3: Что делать, если {{ $json.imageUrls }} в n8n не рендерится?

Есть три наиболее частые причины: во-первых, в узле HTTP Request для JSON Body должен быть включен режим выражений (перед всей строкой JSON стоит знак = или подсвечена кнопка fx слева); во-вторых, путь к полю должен соответствовать реальному выводу предыдущего узла — проверьте это на панели Output после выполнения узла в n8n; в-третьих, если вы используете sub-node, выражение по умолчанию берет только первый элемент (item). Либо переключитесь на основной узел, либо сначала используйте узел Item Lists для развертывания данных.

Q4: Как исправить ошибку с undefined?

Это означает, что в коде вы обращаетесь к несуществующему полю. Самый быстрый способ исправления — добавить проверку перед вызовом Gemini: assert image_url is not None and isinstance(image_url, str). Затем проверьте возвращаемое значение вышестоящего API на предмет правильного имени поля. Частые опечатки: imageUrls vs imageUrl, image_url vs imageUrl, url vs uri. В продакшене рекомендую, как в примере «Исправление 2» в этой статье, отсекать любые строки, не являющиеся https или gs, еще до отправки запроса.

Q5: Можно ли передать несколько изображений напрямую в fileUri?

Нет. fileUri принимает только одну строку. Если нужно передать несколько изображений, правильный подход — создать отдельный элемент { "fileData": { "fileUri": "...", "mimeType": "..." } } для каждого изображения и поместить их все в один массив parts. Только так Gemini сможет правильно распознать семантическую связь между несколькими изображениями.

Q6: Что делать, если приватный бакет или временный URL с подписью нельзя сделать публичными?

Самый надежный вариант — использовать inlineData + base64: считайте изображение на своей стороне, закодируйте его в base64 и вставьте прямо в тело запроса. В этом случае серверу Gemini не нужно скачивать внешние ресурсы, что избавляет от проблем с «ошибками аутентификации / истечением срока действия подписи / несовпадением MIME». Минус в том, что тело запроса станет больше, поэтому этот метод подходит для небольших изображений. Если вы работаете с высоконагруженной генерацией изображений, все равно рекомендуется сначала загрузить изображение в публично доступный CDN, а затем вызывать gemini-3-pro-image-preview через APIYI (apiyi.com). Это позволит избежать раздувания объема base64 и упростит кэширование и повторные попытки на уровне платформы.

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

Итоги: лучшие практики после исправления ошибки Nano Banana Pro

Возвращаясь к конкретной ошибке Nano Banana Pro: Unsupported file URI type: {{ $json.imageUrls }}, мы можем с уверенностью сказать клиенту: проблема не в Gemini. Это n8n или low-code рабочий процесс не заменили шаблонную переменную на реальный URL, из-за чего вся строка {{ ... }} была отправлена в API Gemini как есть. Способ исправления уже описан в разделе «Исправление 1»: достаточно включить режим выражений (expression mode) в JSON Body узла HTTP Request и убедиться, что предыдущий узел действительно передает поле imageUrls. Ошибка исчезнет мгновенно.

В более широком смысле, ошибка Unsupported file URI type подсвечивает распространенную проблему: многим командам при вызове API для работы с изображениями не хватает слоя «валидации входных данных». В итоге, когда Gemini отклоняет запрос, невозможно понять, в чем причина: в самой модели, сети или параметрах. Чек-лист для диагностики за 5 минут, Python-код для проверки и примеры выражений n8n из этой статьи можно смело внедрять как стандартный протокол действий для вашей команды.

🎯 Финальный совет: если вы настраиваете рабочий процесс «текст-в-изображение» на базе gemini-3-pro-image-preview для клиентов, мы рекомендуем централизовать все вызовы Nano Banana Pro через сервис-прокси API, такой как APIYI (apiyi.com). Это позволит не только быстро воспроизводить и сравнивать неудачные запросы в консоли, но и бесшовно переключаться на модели аналогичного уровня, такие как Nano Banana 2 или Seedream, в случае сбоев на стороне Google. Так вы сможете моментально находить и исправлять подобные ошибки параметров.

Автор: Команда APIYI | Фокусируемся на внедрении больших языковых моделей и инженерии стабильности. Больше практических советов по отладке Gemini и API для работы с изображениями вы найдете на сайте 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~

Похожие записи