Istruzioni di integrazione dell'API Nano Banana Images

​

Procedura 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
• Header della richiesta：
  • accept: application/json
  • content-type: application/json
• Azione (action)：
  • generate：genera immagini in base a prompt testuali
  • edit：modifica sulla base delle immagini fornite
• Modello (model)（facoltativo）：
  • 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, con velocità di generazione elevata
  • nano-banana-2：basato su Gemini 3.1 Flash Image Preview, qualità di livello Pro + velocità Flash
  • nano-banana-2.1：modello di immagini efficiente di nuova generazione, supporta la generazione e la modifica di immagini 1K, 2K e 4K
  • nano-banana-pro：basato su Gemini 3 Pro Image Preview, massima qualità
  • nano-banana:official、nano-banana-2-lite:official、nano-banana-2:official、nano-banana-pro:official：versioni dei canali ufficiali dei modelli corrispondenti, con qualità dell’immagine e stabilità migliori, e fatturazione differente
• Callback asincrono：facoltativo, riceve la notifica di completamento dell’attività e il risultato tramite callback_url
• Numero di immagini：facoltativo, specifica 1–4 immagini tramite count, il valore predefinito è 1; ogni immagine viene completata da una chiamata di generazione indipendente; i normali errori tecnici o i rifiuti di sicurezza del provider influiscono solo sulla chiamata corrispondente, mentre le altre immagini generate con successo vengono restituite normalmente e fatturate in base al numero effettivo di immagini riuscite

​

Avvio 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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "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": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​

Esempio di risposta riuscita

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://cdn.acedata.cloud/assets/examples/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336-34b3dc2195e8.png"
    }
  ]
}

​

Descrizione dei campi

• success：se questa richiesta è riuscita.
• task_id：ID dell’attività.
• trace_id：ID di tracciamento della catena, utile per individuare i problemi.
• count：numero di immagini richieste per la generazione o la modifica, supporta 1–4, il valore predefinito è 1. data include solo le immagini generate con successo e la fatturazione avviene in base al numero effettivo di immagini restituite. Ogni chiamata di generazione utilizza obbligatoriamente la politica di sicurezza nativa del provider; il rifiuto di una chiamata non influisce sulle altre chiamate riuscite, mentre viene restituito 403 quando tutte le chiamate vengono rifiutate.
• data[]：elenco dei risultati.
  • prompt：prompt utilizzato per la generazione (riproposto).
  • image_url：URL diretto dell’immagine generata.

Nota: /nano-banana/images richiede solo action e prompt per generare immagini

​

Modifica delle 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": "let this man wear on this 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": "let this man wear on this 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 riuscita

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "let this man wear on this 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 (devono essere accessibili pubblicamente). È possibile passare più immagini; il servizio completerà la modifica combinando questi materiali con il prompt.
• Gli altri campi sono gli stessi della risposta di «Genera immagine».

​

Callback asincrono (opzionale, consigliato)

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 contenente il risultato di base).
3. Quando l’attività è completata, la piattaforma invierà il JSON completo a callback_url tramite POST. Puoi associare la richiesta al risultato tramite task_id.

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

​

Gestione degli errori

• 400 token_mismatched: la richiesta non è valida o i parametri sono errati.
• 400 api_not_implemented: l’interfaccia non è implementata (contatta il supporto).
• 401 invalid_token: autenticazione non riuscita o Token mancante.
• 403 forbidden: la policy di sicurezza nativa del provider ha rifiutato la richiesta o il risultato generato. Questa chiamata non restituirà immagini e non verrà addebitata; le richieste con più immagini possono comunque restituire e addebitare altre chiamate riuscite.
• 429 too_many_requests: frequenza delle richieste oltre il limite.
• 500 api_error: eccezione del server.

​

Esempio di risposta di errore

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Internal server error."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Confronto dei parametri e note

• Obbligatori: action, prompt
• Esclusivi per la modifica: image_urls (array, almeno 1 elemento)
• Opzionali: model (predefinito nano-banana, opzionali nano-banana-2-lite, nano-banana-2, nano-banana-2.1, nano-banana-pro; a eccezione di nano-banana-2.1, sono disponibili anche le corrispondenti versioni del canale ufficiale :official), aspect_ratio (rapporto d’aspetto, ad esempio 1:1, 16:9), resolution (risoluzione, ad esempio 1K, 2K, 4K; nano-banana-2-lite supporta solo 1K), callback_url (per callback asincrono)
• Headers: è obbligatorio fornire authorization: Bearer {token}; si consiglia di impostare accept su application/json
• Accessibilità delle immagini: image_urls deve contenere link diretti accessibili 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