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

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

> Nano Banana Image Generation 集成指南 - XHuoAPI

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

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

Перед використанням, будь ласка, зайдіть на платформу XHuoAPI до [Nano Banana Images API](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) та натисніть Acquire для подачі заявки на активацію. Перший запит зазвичай має безкоштовний ліміт. Після активації ви зможете отримати Bearer Token для виклику API на платформі.

## Огляд інтерфейсу

* **Базовий URL**: `https://api.xhuoapi.ai/v1`
* **Кінцева точка**: `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`: на основі 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)

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "prompt": "Фотореалістичний крупний портрет літнього японського кераміста з глибокими, сонячними зморшками та теплою, усміхненою усмішкою. Він уважно оглядає свіжозроблену чайну чашку. Обстановка - його сільська, залита сонцем майстерня. Сцена освітлена м'яким, золотим світлом, що проникає через вікно, підкреслюючи тонку текстуру глини. Знято з об'єктивом 85 мм, що призводить до м'якого, розмитого фону (боке). Загальний настрій спокійний і майстерний. Вертикальна орієнтація портрету.",
    "count": 1
  }'
```

### Приклад запиту (Python)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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())
```

### Приклад успішного повернення

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

### Опис полів

* `success`: чи була ця запит успішною.
* `task_id`: ID завдання.
* `trace_id`: ID трасування, для полегшення виявлення проблем.
* `data[]`: список результатів.
  * `prompt`: підказка, використана для генерації (відображення).
  * `image_url`: пряма URL-адреса згенерованого зображення.

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

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

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

Наприклад, тут ми надаємо фотографію людини та фотографію одягу, щоб людина одягнула цей одяг, можна одночасно передати URL-адреси зображень і вказати action як `edit`, URL може бути HTTP URL, доступним через публічний доступ, або може бути зображенням у форматі Base64, наприклад `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`

### Приклад запиту (cURL)

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "дозвольте цій людині одягнути цю футболку",
    "image_urls": [
      "https://cdn.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'
```

### Приклад запиту (Python)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "дозвольте цій людині одягнути цю футболку",
    "image_urls": [
        "https://cdn.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/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.xhuoapi.ai/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`.

**Приклад навантаження зворотного виклику** (структура полів така ж, як у синхронному успішному поверненні):

```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.xhuoapi.ai/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` або `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
* **Ідемпотентність та відстеження**: зберігайте `task_id` та `trace_id`, щоб полегшити усунення неполадок та зв'язок результатів