dall-e-2, gpt-image-1, l’ultimo modello gpt-image-2, e la serie di modelli nano-banana / nano-banana-2 / nano-banana-pro integrati tramite la stessa interfaccia.
Questo documento illustra principalmente il flusso operativo dell’OpenAI Images Edits API, che permette di utilizzare facilmente la funzionalità ufficiale di modifica immagini di OpenAI.
Procedura di Richiesta
Per utilizzare OpenAI Images Edits API, puoi visitare la pagina OpenAI Images Edits API e cliccare sul pulsante “Acquire” per ottenere le credenziali necessarie per la richiesta: Se non sei ancora loggato o registrato, verrai automaticamente reindirizzato alla pagina di login per registrarti e accedere; dopo il login verrai riportato automaticamente a questa pagina. Al primo accesso viene fornito un credito gratuito per utilizzare l’API senza costi.Modello GPT-Image-2
gpt-image-2 presenta miglioramenti significativi rispetto a gpt-image-1 nell’ambito della modifica immagini:
- Maggiore stabilità strutturale: Cambiando pelle, colori o sfondo, la composizione e il layout originali dell’immagine rimangono quasi intatti.
- Conservazione più accurata del testo: Immagini contenenti testo come infografiche, poster o menu mantengono il testo nitido e leggibile dopo la modifica.
- Supporto per URL diretti: Oltre al tradizionale caricamento file
multipart/form-data,gpt-image-2supporta anche il passaggio dell’immagine tramite URL in formato JSON, senza necessità di scaricare l’immagine localmente, ideale per pipeline server-side. - Supporto per ridisegno ad alta risoluzione: È possibile fornire un’immagine originale 1K e tramite il parametro
sizerichiedere output 2K o 4K; il modello eseguirà l’ingrandimento durante la modifica.
Valori supportati per size
Le restrizioni sul parametro size nell’API di modifica sono identiche a quelle dell’API di generazione: gpt-image-2 accetta size uguale a auto, vuoto, o nel formato WIDTHxHEIGHT; qualsiasi altro valore restituirà errore 400. Tutte le dimensioni (1K / 2K / 4K / personalizzate) vengono tariffate per singola immagine indipendentemente dalla risoluzione originale o dal valore di size.
Le restrizioni upstream sulle dimensioni personalizzate sono valide anche qui: larghezza e altezza devono essere multipli di 16, lato lungo ≤ 3840, e numero totale di pixel ≤ 8.294.400.
Esempio: se l’immagine originale è1024x1024e si passasize=2048x2048, il modello ridisegnerà e restituirà un’immagine 2K; consize=3840x2160restituirà un’immagine 4K orizzontale; conautoo omesso, il modello sceglierà autonomamente. Il costo è identico in tutti e tre i casi.
Nota sul parametroDi seguito due esempi reali per mostrare le capacità di modifica dinL’API di modificagpt-image-2non supportan > 1: questo parametro viene ignorato silenziosamente, quindi indipendentemente dal valore din(es.n=1on=10), la richiesta restituirà una sola immagine e sarà fatturata come una sola. Se desideri più risultati candidati, devi effettuare più richieste in parallelo. Questa limitazione vale anche pergpt-image-1/gpt-image-1.5e per la serienano-banana/nano-banana-2/nano-banana-pro. Solodall-e-2supporta nativamenten > 1per la modifica.
gpt-image-2.
Metodo 1: JSON + URL immagine (consigliato)
Invia la richiesta in formatoapplication/json con il campo image contenente l’URL di un’immagine; il modello scaricherà l’immagine e la modificherà secondo il prompt.
Ad esempio, questa immagine originale è una infografica generata da gpt-image-2:
Vogliamo convertirla in modalità “dark mode”. La chiamata sarà:
Suggerimento: il campoimagesupporta anche un array, ad esempio"image": ["url1", "url2", "url3"], fino a 16 immagini di riferimento per permettere al modello di considerare più immagini contemporaneamente.
Metodo 2: JSON + più immagini di riferimento
gpt-image-2 supporta la modifica basata su più immagini di riferimento contemporaneamente, ad esempio combinando più foto di prodotti in un unico cesto regalo:
Esempio: Cambio stile mantenendo struttura
Un altro esempio: sostituire una libreria in legno con una mensola moderna sospesa, mantenendo esattamente il numero e la disposizione dei libri su ogni ripiano. Immagine originale (libreria in legno generata dagpt-image-2):
Chiamata:
task_id: e9544dba-727e-44a2-81e1-223d49869380):
Lo stile e l’ambiente sono stati completamente modificati secondo il prompt, ma il numero di libri per ripiano (1 / 3 / 7) è stato rigorosamente mantenuto, con l’aggiunta di una piccola pianta succulenta come richiesto.
Metodo 3: multipart/form-data (compatibile con OpenAI SDK)
Se usi già l’OpenAI Python SDK ufficiale, puoi continuare a caricare conmultipart/form-data, cambiando solo il modello in gpt-image-2:
OPENAI_BASE_URL a https://api.acedata.cloud/openai e OPENAI_API_KEY al token ottenuto:
Serie Nano Banana
La serienano-banana è integrata nell’endpoint /openai/images/edits; basta impostare il parametro model su uno dei modelli della tabella seguente.
Importante: parametri supportati Nano Banana è integrato tramite un layer di adattamento al protocollo OpenAI e supporta solo i parametri:model,prompt,image.
imagepuò essere caricato tramitemultipart/form-data(internamente convertito indata:<mime>;base64,...per l’upstream) oppure passato come URL immagine nel campo form.- Non supporta parametri come
mask,n,size,response_format; se forniti, verranno ignorati.- La struttura di risposta segue il formato OpenAI (
data[].url), macreatedè sempre0, non viene restituitob64_jsonerevised_promptè sempre uguale al prompt originale.
Chiamata con form + URL immagine
Chiamata con form + file locale
Callback asincrono
Il meccanismo di callback asincrono tramitecallback_url è supportato anche da nano-banana, con flusso identico agli altri modelli, come descritto nella sezione Callback asincrono.
Uso base
Ecco un esempio di chiamata con CURL:authorization (selezionabile dal menu a tendina), model (scegli il modello OpenAI, qui disponibile un modello principale, vedi dettagli sopra), prompt (il testo descrittivo per generare l’immagine) e image (il percorso dell’immagine da modificare). L’immagine di esempio è mostrata qui sotto:
Codice Python equivalente:
OPENAI_BASE_URL a https://api.acedata.cloud/openai e OPENAI_API_KEY al token ottenuto, ad esempio su Mac OS:
gift-basket.png, come mostrato:
Così abbiamo completato la modifica dell’immagine. L’API Edits supporta tre modelli: dall-e-2, gpt-image-1 e gpt-image-2, con quest’ultimo raccomandato, come descritto nella sezione Modello GPT-Image-2.
Callback asincrono
Poiché la modifica immagini può richiedere tempo, per evitare che la richiesta HTTP rimanga aperta consumando risorse, l’API supporta callback asincroni. Il flusso è: il client invia la richiesta specificando un campocallback_url; l’API risponde subito con un task_id identificativo del task; al completamento, il risultato viene inviato via POST JSON all’URL indicato, includendo il task_id per correlare la risposta.
Esempio pratico:
Un webhook è un servizio HTTP che riceve richieste; sostituisci con il tuo URL server. Per testare, usa il sito pubblico https://webhook.site/, che fornisce un URL webhook come mostrato:
Copia l’URL, ad esempio https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, e usalo come callback_url nella richiesta:
task_id permette di associare la risposta al task originale; data contiene il risultato della modifica immagine come nella chiamata sincrona.
Gestione errori
In caso di errore, l’API restituisce codici e messaggi appropriati, ad esempio:400 token_mismatched: richiesta errata, parametri mancanti o non validi.400 api_not_implemented: richiesta errata, parametri mancanti o non validi.401 invalid_token: non autorizzato, token mancante o non valido.429 too_many_requests: troppe richieste, superato il limite di velocità.500 api_error: errore interno del server.

