> ## 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`: пряма URL-адреса згенерованого зображення.

> Примітка: `/nano-banana/images` потрібно лише `action` та `prompt`, щоб згенерувати зображення

## Редагування зображення (`action=edit`)

Коли ви хочете редагувати на основі вже існуючого зображення, встановіть `action` на `edit` і передайте список URL-адрес зображень для редагування через `image_urls` (1 або більше), одночасно надаючи опис цілей редагування в `prompt`.

Наприклад, тут ми надаємо фотографію людини та фотографію одягу, щоб людина одягла цей одяг, можна одночасно передати URL-адреси зображень і вказати action як `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
* **Ідемпотентність та відстеження**：зберігайте `task_id` та `trace_id`, щоб полегшити усунення неполадок та зв'язок результатів