Vai al contenuto principale
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 Ace Data Cloud e vai a Nano Banana Images API 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.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 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)

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

import requests

url = "https://api.acedata.cloud/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

{
  "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.acedata.cloud/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)

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