Nano Banana Images API Integracja i Użytkowanie

Ten dokument przedstawia integrację i użytkowanie 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 otrzymasz darmowy limit, aby móc skorzystać z usługi; w przypadku niewystarczającego limitu możesz doładować saldo ogólne w konsoli.

📘 Pełna dokumentacja: Nano Banana Images API →

Przegląd interfejsu

Podstawowy 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-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 opłaty
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; w przypadku częściowych niepowodzeń zwracane są tylko udane obrazy i naliczane są opłaty

Szybki start: Generowanie obrazów (`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",
    "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 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",
    "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 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": "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 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://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: ID zadania.
trace_id: ID śledzenia, ułatwiające rozwiązywanie problemów.
count: Liczba obrazów do wygenerowania lub edytowania, obsługuje 1–4, domyślnie 1. W przypadku częściowych niepowodzeń data zawiera tylko udane obrazy.
data[]: Lista wyników.
- prompt: Użyty do generowania opis (echo).
- image_url: Bezpośredni URL do wygenerowanego obrazu.

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

Edytowanie obrazów (`action=edit`)

Gdy chcesz edytować istniejący obraz, ustaw action na edit i przekaż listę linków do obrazów do edytowania 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 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, 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
  }'

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 udanego zwrotu

{
  "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 „generowania 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 synchronizowanym udanym zwrotem):

{
  "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: 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
Specjalne dla edycji: image_urls (tablica, co najmniej 1 element)
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

Nano Banana Images API Integracja i Użytkowanie

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

Edytowanie obrazów (`action=edit`)

Przykład żądania (cURL)

Przykład udanego zwrotu

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

​Edytowanie obrazów (action=edit)

​Przykład żądania (cURL)

​Przykład udanego zwrotu

​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

Edytowanie obrazów (`action=edit`)

Przykład żądania (cURL)

Przykład udanego zwrotu

Opis pól

Asynchroniczny callback (opcjonalny, zalecany)

Obsługa błędów

Przykład odpowiedzi błędu

Zestawienie parametrów i uwagi