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 заголовок содержит 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 содержит только успешно сгенерированные изображения и тарифицируется по фактическому количеству возвращенных изображений. Каждый вызов генерации обязательно использует оригинальную политику безопасности поставщика; отказ в одном вызове не влияет на другие успешные вызовы, если все вызовы отклонены, возвращается 403.
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
  }'

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

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：Ошибка аутентификации или отсутствует токен.
403 forbidden：Исходная политика безопасности провайдера отклонила запрос или результат генерации. Этот вызов не вернет изображение и не будет тарифицироваться; запросы с несколькими изображениями все равно могут вернуть и тарифицировать другие успешные вызовы.
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

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

Прокси

Продвинутый

Coding

Nano Banana Images API интеграция

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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