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

​
Proces aplikacji

Przed użyciem, proszę przejść na platformę Ace Data Cloud i wejść do Nano Banana Images API oraz kliknąć “Acquire”, aby złożyć wniosek o aktywację. Przy pierwszym wniosku zazwyczaj dostępny jest darmowy limit. Po zakończeniu aktywacji, można uzyskać Bearer Token do wywoływania API na platformie.

​
Przegląd interfejsu

  • Base URL: https://api.acedata.cloud
  • Endpoint: POST /nano-banana/images
  • Metoda autoryzacji: W nagłówku HTTP należy przesłać authorization: Bearer {token}
  • Nagłówki żądania:
    • accept: application/json
    • content-type: application/json
  • Akcja (action):
    • generate: generowanie obrazu na podstawie tekstowego opisu
    • edit: edytowanie na podstawie podanego obrazu
  • Model (model) (opcjonalnie):
    • nano-banana (domyślny): oparty na Gemini 2.5 Flash Image, szybki, niskokosztowy
    • 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ść
  • Asynchroniczny callback: opcjonalnie, można otrzymać powiadomienie o zakończeniu zadania i wyniku przez callback_url

​
Szybki start: generowanie obrazu (action=generate)

Minimalne wymagane parametry: action, prompt Gdy chcesz bezpośrednio wygenerować obraz na podstawie opisu, 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",
    "prompt": "Fotorealistyczny zbliżenie portretu 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 oświetlona jest 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",
    "prompt": (
        "Fotorealistyczny zbliżenie portretu 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 oświetlona jest 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": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "Fotorealistyczny zbliżenie portretu 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 oświetlona jest 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://platform.cdn.acedata.cloud/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}

​
Opis pól

  • success: Czy to żądanie zakończyło się sukcesem.
  • task_id: ID zadania.
  • trace_id: ID śledzenia, ułatwiające rozwiązywanie problemów.
  • data[]: Lista wyników.
    • prompt: Użyty do generacji opis (echo).
    • image_url: Bezpośredni URL do wygenerowanego obrazu.
Uwaga: /nano-banana/images wymaga jedynie action i prompt, aby wygenerować obraz.

​
Edytowanie obrazu (action=edit)

Gdy chcesz edytować istniejący obraz, ustaw action na edit i przekaż listę linków do obrazów do edycji w image_urls (1 lub więcej), jednocześnie podając opis celu edycji w prompt. Na przykład, jeśli dostarczymy zdjęcie osoby oraz 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, np. 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ć publicznie dostępna). Można przesłać wiele obrazów, a usługa połączy te materiały z prompt, aby zakończyć edycję.
  • Pozostałe pola są takie same jak w odpowiedzi „generowanie obrazu”.

​
Asynchroniczne wywołanie zwrotne (opcjonalne, zalecane)

Generowanie lub edytowanie może zająć trochę czasu. Aby uniknąć zajmowania zasobów przez długie połączenia, zaleca się użycie wywołania zwrotnego Webhook przez callback_url:
  1. 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).
  2. API natychmiast zwróci odpowiedź zawierającą task_id (lub podstawowy wynik).
  3. 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 zwrotnego (struktura pól zgodna z synchronizowanym zwrotem 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 jest nieprawidłowe lub parametry są błędne.
  • 400 api_not_implemented: Interfejs nie został zaimplementowany (proszę skontaktować się z pomocą techniczną).
  • 401 invalid_token: Nieudana autoryzacja lub brak tokena.
  • 429 too_many_requests: Przekroczono limit częstotliwości żądań.
  • 500 api_error: Błąd 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
  • Tylko do edycji: image_urls (tablica, co najmniej 1 pozycja)
  • Opcjonalne: model (domyślnie nano-banana, opcjonalnie nano-banana-2 lub nano-banana-pro), aspect_ratio (proporcje, np. 1:1, 16:9), resolution (rozdzielczość, np. 1K, 2K, 4K), callback_url (do asynchronicznego wywołania zwrotnego)
  • 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ć diagnozowanie problemów i powiązanie wyników