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

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

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

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

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

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

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

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

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)

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())

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

{
  "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)

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
  }'

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())

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

{
  "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 зворотного виклику:

Додайте 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": "біла сіамська кішка",
      "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：виклик сервера.

Приклад відповіді з помилкою

{
  "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, щоб полегшити усунення неполадок та зв’язок результатів

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

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

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

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

Швидкий старт: генерація зображення (`action=generate`)

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

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

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

Опис полів

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

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

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

Опис полів

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

Обробка помилок

Приклад відповіді з помилкою

Параметри та зауваження

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

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

​Швидкий старт: генерація зображення (action=generate)

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

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

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

​Опис полів

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

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

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

​Опис полів

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

​Обробка помилок

​Приклад відповіді з помилкою

​Параметри та зауваження

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

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

Швидкий старт: генерація зображення (`action=generate`)

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

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

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

Опис полів

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

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

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

Опис полів

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

Обробка помилок

Приклад відповіді з помилкою

Параметри та зауваження