Nano Banana Images API Integrazione e Utilizzo

​

Processo di Richiesta

📘 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
• Azioni (action):
  • generate: genera un’immagine in base a un testo di prompt
  • edit: modifica un’immagine esistente
• Modelli (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 fatturazione diversa
• 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; ogni immagine è generata tramite chiamate indipendenti; errori tecnici normali o rifiuti di sicurezza da parte del fornitore influenzano solo la chiamata corrispondente, mentre le altre immagini di successo vengono restituite normalmente e fatturate in base al numero effettivo di immagini riuscite

​

Inizio Rapido: Generazione di Immagini (action=generate)

​

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 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 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 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 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 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 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. data contiene solo le immagini generate con successo e viene fatturato in base al numero effettivo di immagini restituite. Ogni chiamata di generazione utilizza forzatamente la politica di sicurezza nativa del fornitore; se una chiamata viene rifiutata, non influisce sulle altre chiamate di successo, mentre se tutte le chiamate vengono rifiutate, viene restituito 403.
• data[]: elenco dei risultati.
  • prompt: il testo di prompt 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)

​

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)

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.

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

• 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.
• 403 forbidden: la politica di sicurezza nativa del fornitore ha rifiutato la richiesta o il risultato generato. Questa chiamata non restituirà immagini e non verrà addebitata; le richieste multiple possono comunque restituire e addebitare altre chiamate riuscite.
• 429 too_many_requests: frequenza di richiesta eccessiva.
• 500 api_error: eccezione 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 di 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