Nano Banana Images API - instrukcja integracji

Niniejszy dokument przedstawia integrację i użycie Nano Banana Images API. Interfejs obsługuje dwie funkcjonalności: generowanie obrazów (generate) oraz edycję obrazów (edit).

Proces aplikacji

Aby korzystać z Nano Banana Images API, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój token API, który należy zachować na przyszłość.

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę. Jeden token API wystarczy do korzystania ze wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi. Przy pierwszym wniosku przyznawana jest darmowa pula, którą można wykorzystać bezpłatnie; w przypadku niewystarczającej puli można doładować saldo ogólne w konsoli.

📘 Pełna dokumentacja: Nano Banana Images API →

Przegląd interfejsu

Base URL: https://api.acedata.cloud
Endpoint: POST /nano-banana/images
Metoda autoryzacji: Nagłówek HTTP zawiera authorization: Bearer {token}
Nagłówki żądania:
- accept: application/json
- content-type: application/json
Akcja (action):
- generate: generowanie obrazu na podstawie podanego tekstu
- edit: edycja na podstawie podanego obrazu
Model (model) (opcjonalnie):
- nano-banana (domyślny): oparty na Gemini 2.5 Flash Image, szybki, niskokosztowy
- nano-banana-2-lite: oparty na Gemini 3.1 Flash Lite Image, obsługuje tylko 1K, szybkie generowanie
- nano-banana-2: oparty na Gemini 3.1 Flash Image Preview, jakość Pro + szybkość Flash
- 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 modeli, lepsza jakość obrazu i stabilność, różne zasady rozliczeń
Asynchroniczny callback: opcjonalnie, przez callback_url można otrzymać powiadomienia o zakończeniu zadania i wyniki
Liczba obrazów: opcjonalnie, przez count można określić 1–4 obrazy, domyślnie 1; każdy obraz jest generowany w osobnym wywołaniu; zwykłe błędy techniczne lub odmowy bezpieczeństwa dostawcy wpływają tylko na odpowiednie wywołanie, pozostałe obrazy są zwracane normalnie i są rozliczane według faktycznej liczby udanych obrazów

Szybki start: generowanie obrazów (`action=generate`)

Minimalne wymagane parametry: action, prompt Gdy chcesz bezpośrednio wygenerować obraz na podstawie podanego tekstu, ustaw action na generate i podaj jasny prompt.

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": "Fotorealistyczny zbliżenie portret starszego japońskiego ceramika z głębokimi, słonecznymi zmarszczkami i ciepłym, pełnym zrozumienia uśmiechem. Starannie bada świeżo pokryty glazurą czajnik. Sceneria to jego rustykowna, nasłoneczniona pracownia. Scena jest oświetlona miękkim, złotym światłem zachodzącego słońca wpadającym przez okno, podkreślającym delikatną teksturę gliny. Uchwycone obiektywem portretowym 85 mm, co skutkuje miękkim, rozmytym tłem (bokeh). Ogólny nastrój jest spokojny i mistrzowski. Orientacja portretowa w pionie.",
    "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": (
        "Fotorealistyczny zbliżenie portret starszego japońskiego ceramika "
        "z głębokimi, słonecznymi zmarszczkami i ciepłym, pełnym zrozumienia uśmiechem. Starannie "
        "bada świeżo pokryty glazurą czajnik. Sceneria to jego rustykowna, nasłoneczniona "
        "pracownia. Scena jest oświetlona miękkim, złotym światłem zachodzącego słońca wpadającym "
        "przez okno, podkreślającym delikatną teksturę gliny. Uchwycone obiektywem portretowym 85 mm, "
        "co skutkuje miękkim, rozmytym tłem (bokeh). Ogólny nastrój jest spokojny i mistrzowski. "
        "Orientacja portretowa w pionie."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Przykład udanej odpowiedzi

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "Fotorealistyczny zbliżenie portret starszego japońskiego ceramika z głębokimi, słonecznymi zmarszczkami i ciepłym, pełnym zrozumienia uśmiechem. Starannie bada świeżo pokryty glazurą czajnik. Sceneria to jego rustykowna, nasłoneczniona pracownia. Scena jest oświetlona miękkim, złotym światłem zachodzącego słońca wpadającym przez okno, podkreślającym delikatną teksturę gliny. Uchwycone obiektywem portretowym 85 mm, co skutkuje miękkim, rozmytym tłem (bokeh). Ogólny nastrój jest spokojny i mistrzowski. Orientacja portretowa w pionie.",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}

Opis pól

success: czy to żądanie zakończyło się sukcesem.
task_id: identyfikator zadania.
trace_id: identyfikator śledzenia, ułatwiający rozwiązywanie problemów.
count: liczba obrazów do wygenerowania lub edytowania, obsługuje 1–4, domyślnie 1. data zawiera tylko obrazy, które zostały pomyślnie wygenerowane, a rozliczenie odbywa się według faktycznej liczby zwróconych obrazów. Każde wywołanie generujące korzysta z oryginalnej polityki bezpieczeństwa dostawcy; jeśli jakieś wywołanie zostanie odrzucone, nie wpłynie to na inne udane wywołania, a jeśli wszystkie wywołania zostaną odrzucone, zwróci 403.
data[]: lista wyników.
- prompt: użyty do generowania tekst (echo).
- image_url: bezpośredni URL do wygenerowanego obrazu.

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

Edycja obrazów (`action=edit`)

Gdy chcesz edytować istniejący obraz, ustaw action na edit i przekaż listę linków do obrazów do edytowania przez image_urls (1 lub więcej), jednocześnie podając opis celu edycji w prompt. Na przykład, jeśli dostarczymy zdjęcie osoby i zdjęcie ubrania, aby osoba mogła założyć to ubranie, możemy jednocześnie przesłać linki do obrazów i określić akcję jako edit. URL może być publicznie dostępnym linkiem HTTP, z protokołem https lub http, lub może być obrazem zakodowanym w Base64, takim jak data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....

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": "niech ten mężczyzna założy tę koszulkę",
    "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": "niech ten mężczyzna założy tę koszulkę",
    "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 udanej odpowiedzi

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "niech ten mężczyzna założy tę koszulkę",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

Opis pól

image_urls[]: lista URL obrazów do edycji (musi być dostępna publicznie). Można przesłać wiele, usługa połączy te materiały z prompt w celu edycji.
Pozostałe pola są takie same jak w odpowiedzi „generowanie obrazów”.

Asynchroniczny callback (opcjonalny, zalecany)

Generowanie lub edytowanie może zająć trochę czasu. Aby uniknąć zajmowania zasobów przez długie połączenia, zaleca się użycie callback_url do Webhook callback:

Dodaj callback_url do ciała żądania, na przykład adres Webhook na swoim serwerze (musi być dostępny publicznie, obsługujący POST JSON).
API natychmiast zwróci odpowiedź zawierającą task_id (lub podstawowy wynik).
Gdy zadanie zostanie zakończone, platforma wyśle pełny JSON do callback_url metodą POST. Możesz powiązać żądanie z wynikiem za pomocą task_id.

Przykład ładunku callback (struktura pól jest zgodna z synchronizowaną odpowiedzią sukcesu):

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "biały kot syjamski",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

Obsługa błędów

W przypadku niepowodzenia wywołania zwróci standardowy format błędu oraz identyfikator śledzenia. Powszechne błędy to:

400 token_mismatched: żądanie nielegalne lub błąd parametrów.
400 api_not_implemented: interfejs nie został zaimplementowany (proszę skontaktować się z pomocą techniczną).
401 invalid_token: niepowodzenie autoryzacji lub brak tokena.
403 forbidden: natywna polityka bezpieczeństwa dostawcy odrzuciła żądanie lub wynik generacji. To wywołanie nie zwróci obrazu i nie będzie obciążane; żądania z wieloma obrazami mogą nadal zwracać i obciążać inne udane wywołania.
429 too_many_requests: przekroczono limit częstotliwości żądań.
500 api_error: wyjątek po stronie serwera.

Przykład odpowiedzi błędu

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Błąd wewnętrzny serwera."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Zestawienie parametrów i uwagi

Wymagane: action, prompt
Specjalne dla edycji: image_urls (tablica, co najmniej 1 pozycja)
Opcjonalne: model (domyślnie nano-banana, opcjonalnie nano-banana-2-lite, nano-banana-2, nano-banana-pro, lub odpowiadająca wersja :official), aspect_ratio (proporcje, np. 1:1, 16:9), resolution (rozdzielczość, np. 1K, 2K, 4K; nano-banana-2-lite obsługuje tylko 1K), callback_url (do asynchronicznego callbacku)
Nagłówki: należy podać authorization: Bearer {token}; accept zaleca się ustawić 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 i powiązanie wyników

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Proxy

Advanced

Coding

Nano Banana Images API - instrukcja integracji

Proces aplikacji

Przegląd interfejsu

Szybki start: generowanie obrazów (`action=generate`)

Przykład żądania (cURL)

Przykład żądania (Python)

Przykład udanej odpowiedzi

Opis pól

Edycja obrazów (`action=edit`)

Przykład żądania (cURL)

Przykład żądania (Python)

Przykład udanej odpowiedzi

Opis pól

Asynchroniczny callback (opcjonalny, zalecany)

Obsługa błędów

Przykład odpowiedzi błędu

Zestawienie parametrów i uwagi

​Proces aplikacji

​Przegląd interfejsu

​Szybki start: generowanie obrazów (action=generate)

​Przykład żądania (cURL)

​Przykład żądania (Python)

​Przykład udanej odpowiedzi

​Opis pól

​Edycja obrazów (action=edit)

​Przykład żądania (cURL)

​Przykład żądania (Python)

​Przykład udanej odpowiedzi

​Opis pól

​Asynchroniczny callback (opcjonalny, zalecany)

​Obsługa błędów

​Przykład odpowiedzi błędu

​Zestawienie parametrów i uwagi

Proces aplikacji

Przegląd interfejsu

Szybki start: generowanie obrazów (`action=generate`)

Przykład żądania (cURL)

Przykład żądania (Python)

Przykład udanej odpowiedzi

Opis pól

Edycja obrazów (`action=edit`)

Przykład żądania (cURL)

Przykład żądania (Python)

Przykład udanej odpowiedzi

Opis pól

Asynchroniczny callback (opcjonalny, zalecany)

Obsługa błędów

Przykład odpowiedzi błędu

Zestawienie parametrów i uwagi