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

> Nano Banana Image Generation API guide - Ace Data Cloud

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

## Processo di Richiesta

Per utilizzare l'API Nano Banana Images, prima di tutto vai al [Pannello di Controllo di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro.

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

Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e a effettuare il login; una volta completato, verrai riportato automaticamente alla pagina corrente.

**Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio.** La prima richiesta ti darà un credito gratuito, per un'esperienza senza costi; se il credito è insufficiente, puoi ricaricare il saldo generale nel [pannello di controllo](https://platform.acedata.cloud/console/coin).

> 📘 Documentazione Completa: [Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images)

## Panoramica dell'Interfaccia

* **Base URL**: `https://api.acedata.cloud`
* **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 a un testo di suggerimento
  * `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-lite`: basato su Gemini 3.1 Flash Lite Image, supporta solo 1K, generazione veloce
  * `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, qualità massima
  * `nano-banana:official`, `nano-banana-2-lite:official`, `nano-banana-2:official`, `nano-banana-pro:official`: versioni ufficiali dei modelli, con qualità e stabilità migliori, con costi diversi
* **Callback Asincrono**: opzionale, ricevi notifiche di completamento del compito e risultati tramite `callback_url`
* **Numero di Immagini**: opzionale, specifica da 1 a 4 immagini tramite `count`, predefinito 1; in caso di parziale fallimento, verranno restituite solo le immagini riuscite e verrà addebitato il costo corrispondente

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

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

### Esempio di Richiesta (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": "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 rustico laboratorio illuminato dal sole. La scena è illuminata da una luce morbida dell'ora d'oro 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 complessiva è serena e maestosa. Orientamento verticale del ritratto.",
    "count": 1
  }'
```

### Esempio di Richiesta (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": (
        "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 rustico laboratorio "
        "illuminato dal sole. La scena è illuminata da una luce morbida dell'ora d'oro 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 complessiva "
        "è 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": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "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 rustico laboratorio illuminato dal sole. La scena è illuminata da una luce morbida dell'ora d'oro 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 complessiva è serena e maestosa. Orientamento verticale del ritratto.",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}
```

### Descrizione dei Campi

* `success`: indica se la richiesta è andata a buon fine.
* `task_id`: ID del compito.
* `trace_id`: ID di tracciamento, utile per la risoluzione dei problemi.
* `count`: numero di immagini richieste per generazione o modifica, supporta da 1 a 4, predefinito 1. In caso di parziale fallimento, `data` conterrà solo le immagini riuscite.
* `data[]`: lista dei risultati.
  * `prompt`: il testo di suggerimento 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, qui forniamo una foto di una persona e una foto di un vestito, per far indossare a quella persona il vestito, 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 possono essere immagini codificate in Base64, come `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`

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

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

### 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.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}
```

### Descrizione dei campi

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

***

## Callback asincrona (opzionale, consigliata)

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

1. Aggiungi `callback_url` nel corpo della richiesta, ad esempio l'indirizzo Webhook del tuo server (deve essere accessibile pubblicamente, supporta POST JSON).
2. L'API restituirà **immediatamente** una risposta contenente `task_id` (o risultati di base).
3. Quando il compito è completato, la piattaforma invierà in modo `POST` il JSON completo a `callback_url`. 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.acedata.cloud/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 considerazioni

* **Obbligatorio**: `action`, `prompt`
* **Solo per modifica**: `image_urls` (array, almeno 1 elemento)
* **Opzionale**: `model` (predefinito `nano-banana`, opzioni `nano-banana-2-lite`, `nano-banana-2`, `nano-banana-pro`, o le versioni ufficiali corrispondenti `:official`), `aspect_ratio` (rapporto d'aspetto, come `1:1`, `16:9`), `resolution` (risoluzione, come `1K`, `2K`, `4K`; `nano-banana-2-lite` supporta solo `1K`), `callback_url` (per callback asincrona)
* **Headers**: è necessario fornire `authorization: Bearer {token}`; `accept` è consigliato 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`, utili per la risoluzione dei problemi e l'associazione dei risultati