> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana Images API Integracja i Użytkowanie

> Nano Banana Image Generation API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Pełna dokumentacja: [Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images)

## 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)

```bash theme={null}
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)

```python theme={null}
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

```json theme={null}
{
  "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)

```bash theme={null}
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
  }'
```

```python theme={null}
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

```json theme={null}
{
  "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**:

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 callback** (struktura pól jest zgodna z synchronizowanym udanym zwrotem):

```json theme={null}
{
  "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

```json theme={null}
{
  "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