Nano Banana Images API Integrazione e Utilizzo

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 per ottenere il tuo API Token, da conservare per uso futuro.

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.

📘 Documentazione Completa: Nano Banana Images API →

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)

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)

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

{
  "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)

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)

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

{
  "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:

Aggiungi callback_url nel corpo della richiesta, ad esempio l’indirizzo Webhook del tuo server (deve essere accessibile pubblicamente, supporta POST JSON).
L’API restituirà immediatamente una risposta contenente task_id (o risultati di base).
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):

{
  "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

{
  "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

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Proxy

Avanzato

Nano Banana Images API Integrazione e Utilizzo

Processo di Richiesta

Panoramica dell’Interfaccia

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

Esempio di Richiesta (cURL)

Esempio di Richiesta (Python)

Esempio di Risposta di Successo

Descrizione dei Campi

Modifica di Immagini (`action=edit`)

Esempio di Richiesta (cURL)

Esempio di Richiesta (Python)

Esempio di risposta di successo

Descrizione dei campi

Callback asincrona (opzionale, consigliata)

Gestione degli errori

Esempio di risposta di errore

Riferimento ai parametri e considerazioni

​Processo di Richiesta

​Panoramica dell’Interfaccia

​Inizio Rapido: Generazione di Immagini (action=generate)

​Esempio di Richiesta (cURL)

​Esempio di Richiesta (Python)

​Esempio di Risposta di Successo

​Descrizione dei Campi

​Modifica di Immagini (action=edit)

​Esempio di Richiesta (cURL)

​Esempio di Richiesta (Python)

​Esempio di risposta di successo

​Descrizione dei campi

​Callback asincrona (opzionale, consigliata)

​Gestione degli errori

​Esempio di risposta di errore

​Riferimento ai parametri e considerazioni

Processo di Richiesta

Panoramica dell’Interfaccia

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

Esempio di Richiesta (cURL)

Esempio di Richiesta (Python)

Esempio di Risposta di Successo

Descrizione dei Campi

Modifica di Immagini (`action=edit`)

Esempio di Richiesta (cURL)

Esempio di Richiesta (Python)

Esempio di risposta di successo

Descrizione dei campi

Callback asincrona (opzionale, consigliata)

Gestione degli errori

Esempio di risposta di errore

Riferimento ai parametri e considerazioni