API

GPT Image 2.5 API

Immagine

L’API GPT Image 2.5 integra nella tua applicazione i modelli più avanzati di OpenAI per generare e modificare immagini. Crea immagini dal testo o modifica immagini di riferimento, con proporzioni flessibili e output in 1K, 2K o 4K. Scegli flare per la generazione quotidiana rapida e di alta qualità, oppure sunburst per lavori creativi impegnativi e modifiche precise.

Autorizzazioni

Bearerstringheaderobbligatorio

Chiave API per autorizzare le richieste

Corpo

application/json

modelstringobbligatorio

gpt-image-2-5

input.promptstringobbligatorio

Descrivi l’immagine che vuoi creare, indicando soggetto, composizione, stile e illuminazione. Per modificare immagini, specifica cosa cambiare e cosa mantenere nei riferimenti. Gli spazi iniziali e finali vengono rimossi.

input.modestringopzionale

Seleziona la variante di GPT Image 2.5. flare è la modalità predefinita e privilegia la velocità per la generazione quotidiana di alta qualità e le iterazioni rapide. sunburst privilegia requisiti di qualità elevati e precisione nelle modifiche, quando è essenziale intervenire con accuratezza sulle immagini di riferimento.

Entrambe le modalità supportano la generazione dal testo e la modifica di immagini. Ometti input.images per generare dal testo oppure fornisci riferimenti da modificare. Per confrontare le modalità, mantieni uguali prompt, riferimenti, proporzioni e risoluzione.

Predefinito: flare

flaresunburst

input.imagesstring[]opzionale

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

input.aspect_ratiostringopzionale

Rapporto tra larghezza e altezza dell’immagine di output. auto consente al modello di scegliere una composizione adatta. Seleziona un rapporto dall’elenco per controllare il formato, ad esempio 1:1 per immagini quadrate, 9:16 per verticali o 16:9 per orizzontali.

Predefinito: auto

auto1:12:33:23:44:39:1616:921:9

input.resolutionstringopzionale

Livello di risoluzione dell’output. Usa i valori in minuscolo 1k, 2k o 4k per selezionare il livello corrispondente. Imposta esplicitamente questo campo quando serve una risoluzione specifica.

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": "gpt-image-2-5",
  "input": {
    "prompt": "Una foto prodotto cinematografica di una fotocamera futuristica a forma di banana"
  }
}'

POST /api/v1/create · HTTP 201

{
  "data": {
    "task_id": "task_example",
    "model": "gpt-image-2-5",
    "status": "processing",
    "credits": 5
  }
}

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": "gpt-image-2-5",
    "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": "gpt-image-2-5",
    "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	12	36	50

Parametri facoltativi omessi: 5 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à.