Группа Nano Banana OSS

Контекст (Сначала прочтите)

Что это: Это бета-группа, в которой выходные изображения предоставляются в виде URL, а не Base64, что снижает накладные расходы на передачу Base64 и улучшает пользовательский опыт. Лучше всего подходит для сценариев, где вы используете URL напрямую. Если у вас нет особых требований и вы можете работать с выводом изображений в кодировке Base64, мы по-прежнему рекомендуем использовать «Normal Default Group» или «NanoBanana Enterprise Group».

Поддерживаемые модели (Nano Banana Pro и Gen 1):

gemini-3-pro-image-preview
gemini-3.1-flash-image-preview
gemini-2.5-flash-image

Начало работы

Попросите администратора включить эту видимую группу

Обратитесь к администратору, чтобы он включил видимую группу NB-OSS для вашей учетной записи (добавьте NB-OSS в разделе «Редактировать сведения о пользователе → Дополнительные видимые группы»).

Экран «Редактировать сведения о пользователе»: добавление группы NB-OSS в разделе Дополнительные видимые группы — Edit User Info: add NB-OSS under Extra Visible Groups

Создайте token: выберите группу NB-OSS

При создании token установите модель тарификации на «тарификация за вызов» и выберите группу NB-OSS (Nano Banana PRO, вывод изображения как URL вместо Base64). Вы меняете только token; формат запроса остается прежним.

Экран создания token: модель тарификации установлена на тарификацию за вызов, группа NB-OSS выбрана, вывод изображения как URL вместо Base64 — Create token: set billing model to per-call billing, select the NB-OSS group (1x) — image output as URL instead of Base64

Замените token и протестируйте

Замените token и выполните тест. Ваш код должен уметь обрабатывать вывод URL — не просто заменяйте Base64; лучше поддерживать оба варианта.

Пример кода

curl --location 'https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent' \
  --header 'Authorization: Bearer sk-' \
  --header 'Content-Type: application/json' \
  --data '{
      "contents": [
          {
              "parts": [
                  {
                      "fileData": {
                          "fileUri": "https://raw.githubusercontent.com/apiyi-api/ai-api-code-samples/refs/heads/main/Vision-API-OpenAI/otter.png",
                          "mimeType": "image/png"
                      }
                  },
                  {
                      "text": "add five dogs"
                  }
              ],
              "role": "user"
          }
      ],
      "generationConfig": {"responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }},
      "safetySettings": []
  }'   > output.json

Пример вывода

URL изображения находится в поле text, а thoughtSignature ниже него — это base64-код процесса рассуждения.

Пример JSON-ответа API: поле text содержит URL изображения, а поле thoughtSignature — это base64-код рассуждения — Response JSON: candidates → content → parts, the image URL is in the text field; thoughtSignature is the base64 of the reasoning

Регион OSS Storage и скорость загрузки

Где хранятся изображения?

URL выходных изображений размещены на Alibaba Cloud OSS в Лос-Анджелесе (запад США, us-west-1, регион Северной Америки). URL выглядят так:

https://<bucket-name>.oss-us-west-1.aliyuncs.com/xxxx.png

Поддоменная часть URL (<bucket-name>, например mycdn-gg) может со временем измениться — не задавайте полный домен жестко в вашем коде или правилах firewall. Если вам нужно сопоставлять домен или добавлять его в allowlist, сопоставляйте суффикс oss-us-west-1.aliyuncs.com (официальный OSS-домен Alibaba Cloud) или, в более широком варианте, разрешайте *.aliyuncs.com.

Загрузки медленные?

Поскольку узел хранения находится в Северной Америке, прямые загрузки из некоторых регионов (например, из материкового Китая) могут быть медленными. Распространенные причины и рекомендации:

Ограничение трафика корпоративной сетью / блокировка allowlist для зарубежного трафика: попросите администратора сети снять лимиты скорости и добавить в allowlist *.oss-us-west-1.aliyuncs.com (или *.aliyuncs.com).
Сразу переносите к себе: скачайте изображение сразу после получения URL и заново загрузите его в свое хранилище / CDN, прежде чем отдавать конечным пользователям — не раскрывайте OSS URL конечным пользователям надолго.
Скачивайте через сервер: если ваша локальная сеть медленная, сначала загрузите через зарубежный сервер (или сервер с хорошим сетевым маршрутом), а затем передайте дальше.

Дополнительные идеи по устранению сетевых проблем (DNS, маршрутизация, международная пропускная способность и т. д.) см. в FAQ: Что делать, если загрузка изображений/видео через CDN медленная?

URL не открывается?

Ключевой момент — восстановить экранированную последовательность \u0026 в выходном JSON обратно в обычный &, игнорируя base64-содержимое после thoughtSignature.

Диаграмма: ссылка на изображение находится в текстовом поле, восстановите экранирование JSON обратно в символ &, и игнорируйте base64-содержимое после thoughtSignature — The image link is in the text field; restore the JSON-escaped & back to the & in the URL, and ignore the base64 after thoughtSignature

Основы

Базовый API

Image API (официальный)

Video API (официальный)

API мультимодального понимания

Текстовый API

Контекст (Сначала прочтите)

Начало работы

Пример кода

Пример вывода

Регион OSS Storage и скорость загрузки

Где хранятся изображения?

Загрузки медленные?

URL не открывается?

​Контекст (Сначала прочтите)

​Начало работы

​Пример кода

​Пример вывода

​Регион OSS Storage и скорость загрузки

​Где хранятся изображения?

​Загрузки медленные?

​URL не открывается?

Контекст (Сначала прочтите)

Начало работы

Пример кода

Пример вывода

Регион OSS Storage и скорость загрузки

Где хранятся изображения?

Загрузки медленные?

URL не открывается?