API

Nano Banana 2 API

Immagine

Nano Banana 2 API combina conoscenza del mondo in tempo reale e ragionamento avanzato per offrire una migliore comprensione dei prompt e risultati visivi più accurati. Genera immagini coerenti con più soggetti in 4K nativo, supporta proporzioni flessibili e crea tipografia globale curata anche in composizioni complesse. Integra Nano Banana 2 API per costruire workflow di immagini più intelligenti, scalabili e di alta qualità.

Autorizzazioni

Bearerstringheaderobbligatorio

Chiave API per autorizzare le richieste

Corpo

application/json

modelstringobbligatorio

nano-banana-2

input.promptstringobbligatorio

Descrivi l’immagine da creare o le modifiche da applicare alle immagini di riferimento. Gli spazi bianchi iniziali e finali vengono rimossi.

Lunghezza massima: 5.000 caratteri

input.imagesstring[]opzionale

URL opzionali delle immagini di riferimento. Usa solo URL HTTPS accessibili pubblicamente. Ometti questo campo per generare immagini da testo.

Numero massimo di elementi: 14

input.aspect_ratiostringopzionale

Rapporto larghezza-altezza dell’output. Auto consente al modello di scegliere.

Predefinito: auto

auto1:12:33:23:44:34:55:49:1616:921:91:44:11:88:1

input.resolutionstringopzionale

Livello di risoluzione dell’output; i valori non distinguono tra maiuscole e minuscole. Ometti il campo o lascialo vuoto per usare il valore predefinito.

Predefinito: 2k

1k2k4k

Esempi di richiesta

POST /api/v1/create

curl -X POST https://nanobanana.io/api/v1/create \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "Una foto prodotto cinematografica di una fotocamera futuristica a forma di banana",
    "aspect_ratio": "1:1",
    "resolution": "2k"
  }
}'

POST /api/v1/create · HTTP 201

{
  "data": {
    "task_id": "task_example",
    "model": "nano-banana-2",
    "status": "processing",
    "credits": 30
  }
}

Interroga questo endpoint usando l’ID attività restituito finché l’attività non viene completata o fallisce. Consigliamo un polling ogni 5 secondi per controllare lo stato più recente.

POST /api/v1/check

{
  "task_id": "task_example"
}

Risposta

Stato dell’attività restituito da POST /api/v1/check. ID, URL e timestamp seguenti sono esempi.

idstringobbligatorio

Identificatore dell’attività in data.id, uguale al task_id inviato nella richiesta di verifica.

statusstringobbligatorio

completed indica che la generazione è riuscita e data.data contiene i risultati. Negli altri stati, data.data è null.

failed_reasonstringopzionale

Restituito solo quando status è failed, per spiegare il motivo dell’errore. Il campo è omesso per completed e processing.

Completata · completed

Gli URL di download sono in data.data.results.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "nano-banana-2",
    "status": "completed",
    "data": {
      "results": [
        "https://example.com/generated.png"
      ],
      "processing_time": 18
    }
  }
}

Altri stati

Con processing o failed, data.data è null. Questo esempio mostra failed: solo failed include failed_reason. Continua le verifiche con processing; interrompile con failed.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "nano-banana-2",
    "status": "failed",
    "data": null,
    "failed_reason": "Generation failed."
  }
}

Consumo di crediti

Crediti consumati per una richiesta che genera un’immagine.

Crediti consumati per una richiesta che genera un’immagine.
Risoluzione	1K	2K	4K
Un’immagine	20	30	40

Parametri facoltativi omessi: 20 crediti

Invia esplicitamente i parametri input indicati per usare la tariffa corrispondente. Le richieste che generano più immagini possono consumare più crediti.

Il campo credits restituito da POST /api/v1/create mostra i crediti addebitati per l’attività.