Руководство по интеграции Nano Banana Images API

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

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

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

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

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

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

Base URL：https://api.acedata.cloud
Endpoint：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-2.1：новое поколение эффективной модели изображений, поддерживает генерацию и редактирование изображений 1K, 2K, 4K
- 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：необязательно, получение уведомления о завершении задачи и результата через callback_url
Количество изображений：необязательно, указывается от 1 до 4 через count, по умолчанию 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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "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": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://cdn.acedata.cloud/assets/examples/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336-34b3dc2195e8.png"
    }
  ]
}

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

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

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

Редактирование изображений（`action=edit`）

Когда вы хотите выполнить редактирование на основе уже существующего изображения, установите action в edit, передайте через image_urls список ссылок на изображения для редактирования (одно или несколько изображений), а также предоставьте prompt, описывающий цель редактирования. Например, здесь мы предоставляем одну фотографию человека и одну фотографию одежды, чтобы человек надел эту одежду, можно одновременно передать ссылки на изображения и указать action как 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": "let this man wear on this T-shirt",
    "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": "let this man wear on this T-shirt",
    "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": "let this man wear on this T-shirt",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

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

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

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

Генерация или редактирование может занять некоторое время. Чтобы избежать использования ресурсов длительным соединением, рекомендуется использовать Webhook-обратный вызов через callback_url:

Добавьте 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": "a white siamese cat",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

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

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

400 token_mismatched: некорректный запрос или ошибка параметров.
400 api_not_implemented: интерфейс не реализован (обратитесь в поддержку).
401 invalid_token: ошибка аутентификации или отсутствует Token.
403 forbidden: встроенная политика безопасности поставщика отклонила запрос или результат генерации. Этот вызов не вернёт изображение и не будет тарифицирован; запросы с несколькими изображениями всё ещё могут вернуть и тарифицировать другие успешные вызовы.
429 too_many_requests: превышен лимит частоты запросов.
500 api_error: исключение на стороне сервера.

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Internal server error."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

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

Обязательные: action, prompt
Только для редактирования: image_urls (массив, не менее 1 элемента)
Необязательные: model (по умолчанию nano-banana, доступны nano-banana-2-lite, nano-banana-2, nano-banana-2.1, nano-banana-pro; кроме nano-banana-2.1, также доступны соответствующие версии официального канала :official), aspect_ratio (соотношение сторон, например 1:1, 16:9), resolution (разрешение, например 1K, 2K, 4K; nano-banana-2-lite поддерживает только 1K), callback_url (для асинхронного обратного вызова)
Headers: необходимо указать authorization: Bearer {token}; accept рекомендуется установить в application/json
Доступность изображений: image_urls должны быть прямыми ссылками, доступными из публичной сети (HTTP/HTTPS), рекомендуется использовать HTTPS
Идемпотентность и отслеживание: сохраняйте 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)

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

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

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

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

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

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