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

# Nano Banana Images API - instrukcja integracji

> Nano Banana Image Generation 集成指南 - XHuoAPI

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ę XHuoAPI i wejść do [Nano Banana Images API](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) 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.xhuoapi.ai/v1`
* **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)

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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

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

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'
```

### Przykład żądania (Python)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### Przykład udanej odpowiedzi

```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.xhuoapi.ai/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):

```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.xhuoapi.ai/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

```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`
* **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