Instrukcja integracji z API Nano Banana Images

​

Proces aplikacji

📘 Pełna dokumentacja: Nano Banana Images API →

​

Przegląd interfejsu

• Base URL：https://api.acedata.cloud
• Endpoint：POST /nano-banana/images
• Metoda uwierzytelniania：przekazanie authorization: Bearer {token} w nagłówku HTTP
• Nagłówki żądania：
  • accept: application/json
  • content-type: application/json
• Akcje (action)：
  • generate：generowanie obrazu na podstawie tekstowego polecenia
  • edit：edycja na podstawie podanego obrazu
• Modele (model)（opcjonalne）：
  • nano-banana（domyślny）：oparty na Gemini 2.5 Flash Image, szybki i tani
  • nano-banana-2-lite：oparty na Gemini 3.1 Flash Lite Image, obsługuje wyłącznie 1K, szybkie generowanie
  • nano-banana-2：oparty na Gemini 3.1 Flash Image Preview, jakość klasy Pro + szybkość Flash
  • nano-banana-2.1：nowa generacja wydajnego modelu obrazowego, obsługuje generowanie i edycję obrazów 1K, 2K oraz 4K
  • nano-banana-pro：oparty na Gemini 3 Pro Image Preview, najwyższa jakość
  • nano-banana:official、nano-banana-2-lite:official、nano-banana-2:official、nano-banana-pro:official：oficjalne wersje kanałów odpowiadających modeli, oferujące lepszą jakość obrazu i stabilność, z innym rozliczaniem
• Asynchroniczne wywołanie zwrotne：opcjonalne, odbieranie powiadomień o ukończeniu zadania i wyników przez callback_url
• Liczba obrazów：opcjonalna, określ 1–4 obrazów przez count, domyślnie 1 obraz; każdy obraz jest tworzony przez niezależne wywołanie generowania; zwykłe błędy techniczne lub odmowa bezpieczeństwa dostawcy wpływają tylko na odpowiednie wywołanie, a pozostałe pomyślnie utworzone obrazy są zwracane normalnie i rozliczane według faktycznej liczby pomyślnie utworzonych obrazów

​

Szybki start: generowanie obrazu（action=generate）

​

Przykład żądania（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
  }'

​

Przykład żądania（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())

​

Przykład pomyślnej odpowiedzi

{
  "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"
    }
  ]
}

​

Opis pól

• success：czy to żądanie zakończyło się powodzeniem.
• task_id：ID zadania.
• trace_id：ID śledzenia przepływu, ułatwiające diagnozowanie problemów.
• count：liczba obrazów do wygenerowania lub edycji w żądaniu, obsługuje 1–4, domyślnie 1. data zawiera wyłącznie pomyślnie wygenerowane obrazy, a rozliczenie odbywa się według faktycznie zwróconej liczby obrazów. Każde wywołanie generowania obowiązkowo wykorzystuje natywną politykę bezpieczeństwa dostawcy; odrzucenie jednego wywołania nie wpływa na inne pomyślne wywołania, a jeśli wszystkie wywołania zostaną odrzucone, zwracany jest kod 403.
• data[]：lista wyników.
  • prompt：polecenie użyte do generowania（zwracane ponownie）。
  • image_url：bezpośredni URL wygenerowanego obrazu.

Uwaga: /nano-banana/images wymaga jedynie action i prompt, aby wygenerować obraz

​

Edycja obrazu（action=edit）

​

Przykład żądania（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
  }'

​

Przykład żądania (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())

​

Przykład pomyślnej odpowiedzi

{
  "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"
    }
  ]
}

​

Opis pól

• image_urls[]: Lista adresów URL obrazów do edycji (musi być dostępna publicznie). Można przekazać wiele obrazów, a usługa połączy te materiały z prompt, aby wykonać edycję.
• Pozostałe pola są takie same jak w odpowiedzi „Generowanie obrazu”.

​

Asynchroniczne wywołanie zwrotne (opcjonalne, zalecane)

1. Dodaj callback_url w treści żądania, na przykład adres Webhook Twojego serwera (musi być dostępny publicznie i obsługiwać POST JSON).
2. API natychmiast zwróci odpowiedź zawierającą task_id (lub zawierającą podstawowy wynik).
3. Po zakończeniu zadania platforma wyśle pełny JSON metodą POST do callback_url. Możesz powiązać żądanie z wynikiem za pomocą 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"
    }
  ]
}

​

Obsługa błędów

• 400 token_mismatched: Żądanie jest nieprawidłowe lub wystąpił błąd parametrów.
• 400 api_not_implemented: Interfejs nie został zaimplementowany (skontaktuj się z pomocą techniczną).
• 401 invalid_token: Uwierzytelnianie nie powiodło się lub brakuje Tokena.
• 403 forbidden: Natywna polityka bezpieczeństwa dostawcy odrzuciła żądanie lub wynik generowania. To wywołanie nie zwróci obrazu i nie zostanie naliczona opłata; żądania wieloobrazowe nadal mogą zwracać i naliczać opłaty za inne pomyślne wywołania.
• 429 too_many_requests: Przekroczono limit częstotliwości żądań.
• 500 api_error: Błąd po stronie serwera.

​

Przykład odpowiedzi błędu

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

​

Porównanie parametrów i uwagi

• Wymagane: action, prompt
• Tylko do edycji: image_urls (tablica, co najmniej 1 element)
• Opcjonalne: model (domyślnie nano-banana, opcjonalnie nano-banana-2-lite, nano-banana-2, nano-banana-2.1, nano-banana-pro; z wyjątkiem nano-banana-2.1, dostępne są również odpowiadające im wersje oficjalnego kanału :official), aspect_ratio (proporcje obrazu, np. 1:1, 16:9), resolution (rozdzielczość, np. 1K, 2K, 4K; nano-banana-2-lite obsługuje tylko 1K), callback_url (do asynchronicznego wywołania zwrotnego)
• Nagłówki: Należy podać authorization: Bearer {token}; zaleca się ustawienie accept na application/json
• Dostępność obrazów: image_urls muszą być bezpośrednimi linkami dostępnymi publicznie (HTTP/HTTPS), zaleca się użycie HTTPS
• Idempotencja i śledzenie: Zachowaj task_id i trace_id, aby ułatwić rozwiązywanie problemów oraz powiązanie wyników