> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Nano Banana Image Generation API guide - Ace Data Cloud

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

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

Чтобы использовать Nano Banana Images API, сначала перейдите в [консоль Ace Data Cloud](https://platform.acedata.cloud/console/applications) и получите ваш API Token для резервного копирования.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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

**Один API Token позволяет вызывать все услуги платформы, не нужно отдельно запрашивать для каждой услуги.** При первом запросе предоставляется бесплатный лимит, чтобы вы могли попробовать; если лимит исчерпан, вы можете пополнить общий баланс в [консоли](https://platform.acedata.cloud/console/coin).

> 📘 Полная документация: [Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images)

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

* **Базовый 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)

```bash theme={null}
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)

```python theme={null}
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())
```

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

```json theme={null}
{
  "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)

```bash theme={null}
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 theme={null}
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())
```

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

```json theme={null}
{
  "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 обратного вызова**:

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

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

```json theme={null}
{
  "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`**：Ошибка на стороне сервера.

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

```json theme={null}
{
  "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` для упрощения устранения неполадок и связи результатов