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

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

Перед использованием, пожалуйста, перейдите на платформу Ace Data Cloud в Nano Banana Images API и нажмите Acquire для подачи заявки на активацию. При первой подаче заявки обычно доступен бесплатный лимит. После завершения активации вы сможете получить Bearer Token для вызова 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: основана на Gemini 3.1 Flash Image Preview, качество Pro + скорость Flash
    • nano-banana-pro: основана на Gemini 3 Pro Image Preview, максимальное качество
  • Асинхронный обратный вызов: необязательно, через callback_url получать уведомления о завершении задачи и результатах

​
Быстрый старт: Генерация изображения (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",
    "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",
    "prompt": (
        "Фотореалистичный крупный план портрета пожилого японского керамиста "
        "с глубокими, солнечными морщинами и теплой, знающей улыбкой. Он внимательно "
        "осматривает только что глазурованный чайный бокал. Обстановка - его деревенская, "
        "залитая солнцем мастерская. Сцена освещена мягким светом золотого часа, проникающим "
        "через окно, подчеркивающим тонкую текстуру глины. Снято с помощью портретного "
        "объектива 85 мм, что приводит к мягкому, размытым фону (боке). Общая атмосфера "
        "спокойная и мастерская. Вертикальная ориентация портрета."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

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

{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "Фотореалистичный крупный план портрета пожилого японского керамиста с глубокими, солнечными морщинами и теплой, знающей улыбкой. Он внимательно осматривает только что глазурованный чайный бокал. Обстановка - его деревенская, залитая солнцем мастерская. Сцена освещена мягким светом золотого часа, проникающим через окно, подчеркивающим тонкую текстуру глины. Снято с помощью портретного объектива 85 мм, что приводит к мягкому, размытым фону (боке). Общая атмосфера спокойная и мастерская. Вертикальная ориентация портрета.",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}

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

  • success: успешность данного запроса.
  • task_id: ID задачи.
  • trace_id: ID трассировки, для упрощения поиска проблем.
  • 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 для завершения редактирования.
  • Остальные поля аналогичны возвращаемым при «генерации изображения».

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

Генерация или редактирование может занять некоторое время. Чтобы избежать длительного соединения, которое занимает ресурсы, рекомендуется использовать Webhook обратный вызов через callback_url:
  1. Добавьте callback_url в тело запроса, например, адрес вашего сервера Webhook (должен быть доступен из интернета, поддерживать POST JSON).
  2. API немедленно вернет ответ, содержащий task_id (или основные результаты).
  3. Когда задача будет завершена, платформа отправит полный 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 или nano-banana-pro), aspect_ratio (соотношение сторон, например, 1:1, 16:9), resolution (разрешение, например, 1K, 2K, 4K), callback_url (для асинхронного обратного вызова)
  • Заголовки: необходимо предоставить authorization: Bearer {token}; accept рекомендуется установить на application/json
  • Доступность изображений: image_urls должны быть прямыми ссылками, доступными из интернета (HTTP/HTTPS), рекомендуется использовать HTTPS
  • Идempotentность и отслеживание: сохраняйте task_id и trace_id для упрощения устранения неполадок и связывания результатов