> ## 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 Integrazione e Utilizzo

> Nano Banana Image Generation 集成指南 - XHuoAPI

Questo documento descrive l'integrazione e l'uso dell'API Nano Banana Images. Questa interfaccia supporta due capacità: **generazione di immagini (generate)** e **modifica di immagini (edit)**.

## Processo di Richiesta

Prima di utilizzare, accedi alla piattaforma XHuoAPI e vai a [Nano Banana Images API](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) e clicca su Acquire per richiedere l'attivazione. La prima richiesta di solito avrà un credito gratuito disponibile. Una volta completata l'attivazione, potrai ottenere il Bearer Token necessario per chiamare l'API.

## Panoramica dell'Interfaccia

* **Base URL**: `https://api.xhuoapi.ai/v1`
* **Endpoint**: `POST /nano-banana/images`
* **Metodo di Autenticazione**: Includere `authorization: Bearer {token}` nell'HTTP Header
* **Intestazioni della Richiesta**:
  * `accept: application/json`
  * `content-type: application/json`
* **Azione (action)**:
  * `generate`: genera un'immagine in base al testo di input
  * `edit`: modifica un'immagine esistente
* **Modello (model)** (opzionale):
  * `nano-banana` (predefinito): basato su Gemini 2.5 Flash Image, veloce e a basso costo
  * `nano-banana-2`: basato su Gemini 3.1 Flash Image Preview, qualità Pro + velocità Flash
  * `nano-banana-pro`: basato su Gemini 3 Pro Image Preview, massima qualità
* **Callback Asincrono**: opzionale, ricevi notifiche di completamento del compito e risultati tramite `callback_url`

## Inizio Rapido: Generazione di Immagini (`action=generate`)

**Parametri Minimi Necessari**: `action`, `prompt`
Quando desideri generare un'immagine direttamente in base al testo di input, imposta `action` su `generate` e fornisci un `prompt` chiaro.

### Esempio di Richiesta (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": "Un ritratto ravvicinato fotorealistico di un anziano ceramista giapponese con profonde rughe incise dal sole e un sorriso caldo e consapevole. Sta ispezionando con cura una ciotola da tè appena smaltata. L'ambientazione è il suo laboratorio rustico e soleggiato. La scena è illuminata da una luce morbida dell'ora dorata che filtra attraverso una finestra, evidenziando la fine texture dell'argilla. Catturato con un obiettivo da ritratto da 85 mm, risultando in uno sfondo morbido e sfocato (bokeh). L'atmosfera generale è serena e maestosa. Orientamento verticale del ritratto.",
    "count": 1
  }'
```

### Esempio di Richiesta (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": (
        "Un ritratto ravvicinato fotorealistico di un anziano ceramista giapponese "
        "con profonde rughe incise dal sole e un sorriso caldo e consapevole. Sta ispezionando "
        "con cura una ciotola da tè appena smaltata. L'ambientazione è il suo laboratorio rustico e "
        "soleggiato. La scena è illuminata da una luce morbida dell'ora dorata che filtra attraverso "
        "una finestra, evidenziando la fine texture dell'argilla. Catturato con un obiettivo da ritratto "
        "da 85 mm, risultando in uno sfondo morbido e sfocato (bokeh). L'atmosfera generale è serena e "
        "maestosa. Orientamento verticale del ritratto."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### Esempio di Risposta di Successo

```json theme={null}
{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "Un ritratto ravvicinato fotorealistico di un anziano ceramista giapponese con profonde rughe incise dal sole e un sorriso caldo e consapevole. Sta ispezionando con cura una ciotola da tè appena smaltata. L'ambientazione è il suo laboratorio rustico e soleggiato. La scena è illuminata da una luce morbida dell'ora dorata che filtra attraverso una finestra, evidenziando la fine texture dell'argilla. Catturato con un obiettivo da ritratto da 85 mm, risultando in uno sfondo morbido e sfocato (bokeh). L'atmosfera generale è serena e maestosa. Orientamento verticale del ritratto.",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}
```

### Descrizione dei Campi

* `success`: indica se la richiesta è stata completata con successo.
* `task_id`: ID del compito.
* `trace_id`: ID di tracciamento, utile per la risoluzione dei problemi.
* `data[]`: elenco dei risultati.
  * `prompt`: testo di input utilizzato per la generazione (echo).
  * `image_url`: URL diretto dell'immagine generata.

> Nota: `/nano-banana/images` richiede solo `action` e `prompt` per generare un'immagine.

## Modifica di Immagini (`action=edit`)

Quando desideri modificare un'immagine esistente, imposta `action` su `edit` e fornisci un elenco di URL delle immagini da modificare tramite `image_urls` (1 o più immagini), insieme a un `prompt` che descrive l'obiettivo della modifica.

Ad esempio, se forniamo una foto di una persona e una foto di un vestito, per far indossare il vestito alla persona, possiamo inviare gli URL delle immagini e specificare l'azione come `edit`. Gli URL possono essere link pubblicamente accessibili tramite protocollo `https` o `http`, oppure immagini codificate in Base64, come `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`

### Esempio di Richiesta (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": "lascia che quest'uomo indossi questa T-shirt",
    "image_urls": [
      "https://cdn.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'
```

### Esempio di Richiesta (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": "lascia che quest'uomo indossi questa T-shirt",
    "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())
```

### Esempio di Risposta di Successo

```json theme={null}
{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "lascia che quest'uomo indossi questa T-shirt",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}
```

### Descrizione dei Campi

* `image_urls[]`: elenco degli URL delle immagini da modificare (deve essere accessibile pubblicamente). Puoi inviare più immagini, il servizio combinerà questi materiali con il `prompt` per completare la modifica.
* Gli altri campi sono gli stessi della risposta per la "generazione di immagini".

***

## Callback asincrono (opzionale, consigliato)

La generazione o la modifica potrebbero richiedere del tempo. Per evitare che le connessioni lunghe occupino risorse, si consiglia di utilizzare **Webhook callback** tramite `callback_url`:

1. Aggiungi `callback_url` nel corpo della richiesta, ad esempio l'indirizzo Webhook del tuo server (deve essere accessibile pubblicamente e supportare POST JSON).
2. L'API restituirà **immediatamente** una risposta contenente `task_id` (o risultati di base).
3. Quando il compito è completato, la piattaforma invierà un JSON completo a `callback_url` tramite `POST`. Puoi associare la richiesta ai risultati tramite `task_id`.

**Esempio di payload di callback** (la struttura dei campi è la stessa della risposta di successo sincrona):

```json theme={null}
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "un gatto siamese bianco",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}
```

***

## Gestione degli errori

In caso di chiamata fallita, verrà restituito un formato di errore standard con l'ID di tracciamento. Gli errori comuni sono i seguenti:

* **400 `token_mismatched`**: richiesta non valida o errore nei parametri.
* **400 `api_not_implemented`**: interfaccia non implementata (contattare il supporto).
* **401 `invalid_token`**: autenticazione fallita o token mancante.
* **429 `too_many_requests`**: frequenza di richiesta eccessiva.
* **500 `api_error`**: errore del server.

### Esempio di risposta di errore

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Errore interno del server."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

***

## Riferimento ai parametri e note

* **Obbligatorio**: `action`, `prompt`
* **Solo per modifica**: `image_urls` (array, almeno 1 elemento)
* **Opzionale**: `model` (predefinito `nano-banana`, opzionale `nano-banana-2` o `nano-banana-pro`), `aspect_ratio` (rapporto d'aspetto, come `1:1`, `16:9`), `resolution` (risoluzione, come `1K`, `2K`, `4K`), `callback_url` (per callback asincroni)
* **Headers**: deve essere fornito `authorization: Bearer {token}`; `accept` si consiglia di impostarlo su `application/json`
* **Accessibilità delle immagini**: `image_urls` deve essere un link diretto accessibile pubblicamente (HTTP/HTTPS), si consiglia di utilizzare HTTPS
* **Idempotenza e tracciamento**: conserva `task_id` e `trace_id`, per facilitare la risoluzione dei problemi e l'associazione dei risultati