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

> Примечание: для `/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.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
* **Идempotentность и отслеживание**: сохраняйте `task_id` и `trace_id` для упрощения устранения неполадок и связывания результатов