Інструкція з інтеграції Nano Banana Images API

​

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

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

​

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

• Base URL：https://api.acedata.cloud
• Endpoint：POST /nano-banana/images
• Спосіб автентифікації：передача authorization: Bearer {token} в HTTP Header
• Заголовки запиту：
  • 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-2.1：нове покоління ефективної моделі зображень, підтримує генерацію та редагування зображень 1K, 2K, 4K
  • 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：необов’язково, отримуйте сповіщення про завершення завдання та результат через callback_url
• Кількість зображень：необов’язково, вкажіть 1–4 зображення через count, за замовчуванням 1; кожне зображення створюється окремим викликом генерації; звичайні технічні збої або відмови постачальника через безпеку впливають лише на відповідний виклик, інші успішні зображення повертаються як зазвичай, а тарифікація здійснюється за фактичною кількістю успішних зображень

​

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

​

Приклад запиту（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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "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": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://cdn.acedata.cloud/assets/examples/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336-34b3dc2195e8.png"
    }
  ]
}

​

Опис полів

• success：чи був цей запит успішним.
• task_id：ID завдання.
• trace_id：ID відстеження ланцюжка, зручний для діагностики проблем.
• count：кількість зображень, запитаних для генерації або редагування, підтримує 1–4, за замовчуванням 1. data містить лише успішно створені зображення, а тарифікація здійснюється за фактичною кількістю повернених зображень. Кожен виклик генерації примусово використовує власні політики безпеки постачальника; відхилення одного виклику не впливає на інші успішні виклики, а якщо всі виклики відхилено, повертається 403.
• data[]：список результатів.
  • prompt：промпт, використаний для генерації（повторно відображається）.
  • image_url：URL прямого посилання на згенероване зображення.

Примітка：для генерації зображення в /nano-banana/images достатньо лише action та prompt

​

Редагування зображень（action=edit）

​

Приклад запиту（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": "let this man wear on this T-shirt",
    "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": "let this man wear on this T-shirt",
    "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": "let this man wear on this T-shirt",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

​

Опис полів

• image_urls[]: список URL зображень для редагування (мають бути доступні публічно). Можна передати кілька зображень, сервіс поєднає ці матеріали з prompt для виконання редагування.
• Інші поля такі самі, як у відповіді «генерація зображення».

​

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

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": "a white siamese cat",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

​

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

• 400 token_mismatched: запит некоректний або помилка параметрів.
• 400 api_not_implemented: інтерфейс не реалізований (зверніться до підтримки).
• 401 invalid_token: помилка автентифікації або відсутній Token.
• 403 forbidden: вбудована політика безпеки постачальника відхилила запит або результат генерації. Це звернення не поверне зображення та не буде тарифікуватися; запити з кількома зображеннями все ще можуть повертати та тарифікувати інші успішні виклики.
• 429 too_many_requests: перевищено ліміт частоти запитів.
• 500 api_error: помилка сервера.

​

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Internal server error."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Відповідність параметрів і зауваження

• Обов’язкові: action, prompt
• Лише для редагування: image_urls (масив, щонайменше 1 елемент)
• Необов’язкові: model (за замовчуванням nano-banana, доступні nano-banana-2-lite, nano-banana-2, nano-banana-2.1, nano-banana-pro; окрім nano-banana-2.1, також доступні відповідні версії офіційного каналу :official), aspect_ratio (співвідношення сторін, наприклад 1:1, 16:9), resolution (роздільна здатність, наприклад 1K, 2K, 4K; nano-banana-2-lite підтримує лише 1K), callback_url (для асинхронного зворотного виклику)
• Headers: обов’язково потрібно надати authorization: Bearer {token}; accept рекомендується встановити як application/json
• Доступність зображень: image_urls мають бути прямими посиланнями, доступними публічно (HTTP/HTTPS), рекомендується використовувати HTTPS
• Ідемпотентність і відстеження: зберігайте task_id і trace_id для полегшення усунення несправностей і пов’язування результатів