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

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

Перед використанням, будь ласка, зайдіть на платформу Ace Data Cloud до Nano Banana Images API та натисніть Acquire для подачі заявки на активацію. Перший запит зазвичай має безкоштовний ліміт. Після активації ви зможете отримати Bearer Token для виклику 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: на основі 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)

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",
    "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",
    "prompt": (
        "Фотореалістичний крупний портрет літнього японського кераміста "
        "з глибокими, сонячними зморшками та теплою, усміхненою усмішкою. Він уважно "
        "оглядає свіжозроблену чайну чашку. Обстановка - його сільська, залита сонцем "
        "майстерня. Сцена освітлена м'яким, золотим світлом, що проникає через "
        "вікно, підкреслюючи тонку текстуру глини. Знято з об'єктивом 85 мм "
        "з м'яким, розмитим фоном (боке). Загальний настрій спокійний і майстерний. "
        "Вертикальна орієнтація портрету."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

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

{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "Фотореалістичний крупний портрет літнього японського кераміста з глибокими, сонячними зморшками та теплою, усміхненою усмішкою. Він уважно оглядає свіжозроблену чайну чашку. Обстановка - його сільська, залита сонцем майстерня. Сцена освітлена м'яким, золотим світлом, що проникає через вікно, підкреслюючи тонку текстуру глини. Знято з об'єктивом 85 мм, що призводить до м'якого, розмитого фону (боке). Загальний настрій спокійний і майстерний. Вертикальна орієнтація портрету.",
      "image_url": "https://platform.cdn.acedata.cloud/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)

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)

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 для завершення редагування.
  • Інші поля аналогічні поверненню «генерації зображення».

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

Генерація або редагування може зайняти певний час. Щоб уникнути тривалих з’єднань, які займають ресурси, рекомендується використовувати Webhook зворотний виклик через callback_url:
  1. Додайте callback_url до тіла запиту, наприклад, адресу вашого сервера Webhook (повинна бути доступною з Інтернету, підтримувати POST JSON).
  2. API відразу поверне відповідь, що містить task_id (або базовий результат).
  3. Коли завдання буде завершено, платформа надішле повний 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 або 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, щоб полегшити усунення неполадок та зв’язок результатів