Nano Banana Images API Инструкция по интеграции

В этой статье представлена интеграция и использование Nano Banana Images API. Этот интерфейс поддерживает две функции: генерация изображений (generate) и редактирование изображений (edit).

Процесс подачи заявки

Чтобы использовать Nano Banana Images API, сначала перейдите в консоль Ace Data Cloud и получите ваш API Token для резервного копирования.

Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, где вас пригласят зарегистрироваться и войти. После завершения вы будете автоматически возвращены на текущую страницу. Один API Token позволяет вызывать все услуги платформы, не нужно отдельно запрашивать для каждой услуги. При первом запросе предоставляется бесплатный лимит, чтобы вы могли попробовать; если лимит исчерпан, вы можете пополнить общий баланс в консоли.

📘 Полная документация: Nano Banana Images API →

Обзор интерфейса

Базовый URL: https://api.acedata.cloud
Конечная точка: POST /nano-banana/images
Метод аутентификации: HTTP Header с authorization: Bearer {token}
Заголовки запроса:
- accept: application/json
- content-type: application/json
Действие (action):
- generate: генерировать изображение на основе текстового запроса
- edit: редактировать на основе данного изображения
Модель (model) (необязательно):
- nano-banana (по умолчанию): основана на Gemini 2.5 Flash Image, быстрая, низкая стоимость
- nano-banana-2-lite: основана на Gemini 3.1 Flash Lite Image, поддерживает только 1K, быстрая генерация
- nano-banana-2: основана на Gemini 3.1 Flash Image Preview, качество Pro + скорость Flash
- nano-banana-pro: основана на Gemini 3 Pro Image Preview, максимальное качество
- nano-banana:official, nano-banana-2-lite:official, nano-banana-2:official, nano-banana-pro:official: официальные версии соответствующих моделей, лучшее качество и стабильность, различная тарификация
Асинхронный обратный вызов: необязательно, через callback_url получать уведомления о завершении задачи и результатах
Количество изображений: необязательно, через count указать 1–4 изображения, по умолчанию 1; в случае частичного сбоя возвращаются и тарифицируются только успешные изображения

Быстрый старт: генерация изображения (`action=generate`)

Минимально необходимые параметры: action, prompt Когда вы хотите сгенерировать изображение на основе текстового запроса, установите action в generate и предоставьте четкий prompt.

Пример запроса (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": "Фотореалистичный крупный план портрета пожилого японского керамиста с глубокими, солнечными морщинами и теплой, знающей улыбкой. Он внимательно осматривает только что глазурованный чайный бокал. Обстановка - его деревенская, залитая солнцем мастерская. Сцена освещена мягким светом золотого часа, проникающим через окно, подчеркивающим тонкую текстуру глины. Снято с помощью портретного объектива 85 мм, что приводит к мягкому, размытым фону (боке). Общая атмосфера спокойная и мастерская. Вертикальная ориентация портрета.",
    "count": 1
  }'

Пример запроса (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": (
        "Фотореалистичный крупный план портрета пожилого японского керамиста "
        "с глубокими, солнечными морщинами и теплой, знающей улыбкой. Он внимательно "
        "осматривает только что глазурованный чайный бокал. Обстановка - его деревенская, "
        "залитая солнцем мастерская. Сцена освещена мягким светом золотого часа, проникающим "
        "через окно, подчеркивающим тонкую текстуру глины. Снято с помощью портретного "
        "объектива 85 мм, что приводит к мягкому, размытым фону (боке). Общая атмосфера "
        "спокойная и мастерская. Вертикальная ориентация портрета."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Пример успешного ответа

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "Фотореалистичный крупный план портрета пожилого японского керамиста с глубокими, солнечными морщинами и теплой, знающей улыбкой. Он внимательно осматривает только что глазурованный чайный бокал. Обстановка - его деревенская, залитая солнцем мастерская. Сцена освещена мягким светом золотого часа, проникающим через окно, подчеркивающим тонкую текстуру глины. Снято с помощью портретного объектива 85 мм, что приводит к мягкому, размытым фону (боке). Общая атмосфера спокойная и мастерская. Вертикальная ориентация портрета.",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}

Описание полей

success: успешность данного запроса.
task_id: ID задачи.
trace_id: ID трассировки, для упрощения поиска проблем.
count: количество запрашиваемых изображений для генерации или редактирования, поддерживает 1–4, по умолчанию 1. В случае частичного сбоя data содержит только успешные изображения.
data[]: список результатов.
- prompt: использованный для генерации текстовый запрос (эхо).
- image_url: прямая ссылка на сгенерированное изображение.

Примечание: для /nano-banana/images достаточно указать только action и prompt для генерации изображения.

Редактирование изображения (`action=edit`)

Когда вы хотите редактировать на основе уже существующего изображения, установите action в edit и передайте список ссылок на изображения для редактирования через image_urls (1 или более изображений), одновременно предоставив описание цели редактирования в prompt. Например, здесь мы предоставляем фотографию человека и фотографию одежды, чтобы человек надел эту одежду, можно одновременно передать ссылки на изображения и указать действие как edit, URL может быть HTTP URL, общедоступная ссылка с протоколом https или http, также может быть изображение в кодировке Base64, например data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....

Пример запроса (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "пусть этот человек наденет эту футболку",
    "image_urls": [
      "https://cdn.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
  }'

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "пусть этот человек наденет эту футболку",
    "image_urls": [
        "https://cdn.acedata.cloud/v8073y.png",
        "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Пример успешного ответа

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "пусть этот человек наденет эту футболку",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

Описание полей

image_urls[]：Список URL изображений для редактирования (должны быть доступны из интернета). Можно передать несколько, сервис объединит эти материалы с prompt для завершения редактирования.
Остальные поля аналогичны ответу «Создание изображения».

Асинхронный обратный вызов (опционально, рекомендуется)

Создание или редактирование может занять некоторое время. Чтобы избежать длительного соединения, рекомендуется использовать callback_url для Webhook обратного вызова:

Добавьте callback_url в тело запроса, например, адрес вашего сервера Webhook (должен быть доступен из интернета, поддерживать POST JSON).
API немедленно вернет ответ, содержащий task_id (или базовый результат).
Когда задача будет завершена, платформа отправит полный JSON на callback_url с помощью POST. Вы можете связать запрос с результатом по task_id.

Пример нагрузки обратного вызова (структура полей аналогична синхронному успешному ответу):

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "белый сиамский кот",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

Обработка ошибок

При неудачном вызове будет возвращен стандартный формат ошибки и идентификатор трассировки. Распространенные ошибки:

400 token_mismatched：Запрос недействителен или ошибка параметров.
400 api_not_implemented：Интерфейс не реализован (пожалуйста, свяжитесь с поддержкой).
401 invalid_token：Ошибка аутентификации или отсутствует токен.
429 too_many_requests：Превышена частота запросов.
500 api_error：Ошибка на стороне сервера.

Пример ответа об ошибке

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Внутренняя ошибка сервера."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Сопоставление параметров и замечания

Обязательные：action、prompt
Специально для редактирования：image_urls（массив, минимум 1 элемент）
Опционально：model（по умолчанию nano-banana，можно выбрать nano-banana-2-lite、nano-banana-2、nano-banana-pro，или соответствующую версию :official），aspect_ratio（соотношение сторон, например 1:1、16:9），resolution（разрешение, например 1K、2K、4K；nano-banana-2-lite поддерживает только 1K），callback_url（для асинхронного обратного вызова）
Заголовки：Необходимо предоставить authorization: Bearer {token}；accept рекомендуется установить на application/json
Доступность изображений：image_urls должны быть прямыми ссылками, доступными из интернета (HTTP/HTTPS), рекомендуется использовать HTTPS
Идempotentность и трассировка：Сохраните task_id и trace_id для упрощения устранения неполадок и связи результатов

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

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Прокси

Продвинутый

Nano Banana Images API Инструкция по интеграции

Процесс подачи заявки

Обзор интерфейса

Быстрый старт: генерация изображения (`action=generate`)

Пример запроса (cURL)

Пример запроса (Python)

Пример успешного ответа

Описание полей

Редактирование изображения (`action=edit`)

Пример запроса (cURL)

Пример успешного ответа

Описание полей

Асинхронный обратный вызов (опционально, рекомендуется)

Обработка ошибок

Пример ответа об ошибке

Сопоставление параметров и замечания

​Процесс подачи заявки

​Обзор интерфейса

​Быстрый старт: генерация изображения (action=generate)

​Пример запроса (cURL)

​Пример запроса (Python)

​Пример успешного ответа

​Описание полей

​Редактирование изображения (action=edit)

​Пример запроса (cURL)

​Пример успешного ответа

​Описание полей

​Асинхронный обратный вызов (опционально, рекомендуется)

​Обработка ошибок

​Пример ответа об ошибке

​Сопоставление параметров и замечания

Процесс подачи заявки

Обзор интерфейса

Быстрый старт: генерация изображения (`action=generate`)

Пример запроса (cURL)

Пример запроса (Python)

Пример успешного ответа

Описание полей

Редактирование изображения (`action=edit`)

Пример запроса (cURL)

Пример успешного ответа

Описание полей

Асинхронный обратный вызов (опционально, рекомендуется)

Обработка ошибок

Пример ответа об ошибке

Сопоставление параметров и замечания