dall-e-2, gpt-image-1, l’ultima gpt-image-2, e i modelli della serie nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro tramite la stessa interfaccia.
Questo documento descrive principalmente il processo di utilizzo dell’API OpenAI Images Edits, permettendoci di utilizzare facilmente le funzionalità di editing delle immagini ufficiali di OpenAI.
Processo di Richiesta
Per utilizzare l’API OpenAI Images Edits, prima di tutto vai al Pannello di Controllo di Ace Data Cloud per ottenere il tuo API Token, da tenere come riserva.
Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente.
Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio. La prima richiesta ti darà un credito gratuito, permettendoti di provare senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.
📘 Documentazione Completa: OpenAI Images Edits API →
Modello GPT-Image-2
gpt-image-2 presenta miglioramenti molto evidenti rispetto a gpt-image-1 nel contesto dell’editing delle immagini:
- Struttura più stabile: Cambiando la pelle, i colori o lo sfondo, non si danneggia quasi mai la composizione e il layout dell’immagine originale.
- Testo mantenuto con maggiore precisione: Immagini contenenti testo come infografiche, manifesti, menu, ecc., rimangono chiare e leggibili anche dopo la modifica.
- Supporto per invio diretto di URL: Oltre al tradizionale caricamento di file
multipart/form-data,gpt-image-2supporta anche l’invio di URL delle immagini in formato JSON, senza necessità di scaricare prima le immagini localmente, molto adatto per integrazioni in pipeline server. - Supporto per invio diretto di base64: In linea con l’ufficiale, il campo
imagepuò anche ricevere direttamente base64 (data:image/png;base64,...o base64 nudo), permettendo di modificare immagini locali senza doverle caricare prima su un servizio di hosting. - Supporto per ridisegno ad alta risoluzione: È possibile inviare un’immagine originale da 1K e richiedere un output 2K / 4K tramite il parametro
size, il modello completerà l’ingrandimento durante il processo di editing.
Percorsi di Transito Ufficiali / Varianti Inversi (:official / :reverse)
gpt-image-2 utilizza per default il percorso inverso. È possibile scegliere esplicitamente il percorso tramite il suffisso del nome del modello:
gpt-image-2:official: Percorso di transito ufficiale. Supportan > 1(restituzione di più immagini in una volta) e vero 2K / 4K, con addebito per ogni immagine, il prezzo è il doppio di quello di default digpt-image-2. Attualmente fornito solo dal canale openai-hk; se il percorso non è disponibile, restituisce direttamente un errore, senza degradare al percorso inverso.gpt-image-2:reverse: Equivalente algpt-image-2di default (percorso inverso), senza variazione di prezzo.
Le limitazioni relative al parametro “n” di seguito si applicano solo ai percorsi di default / inverso;gpt-image-2:officialsupportan > 1e addebita per immagine.
Valori Supportati per size
Le restrizioni dell’interfaccia di editing per size sono completamente identiche a quelle dell’interfaccia di generazione: gpt-image-2 richiede che size sia auto, vuoto, o conforme al formato WIDTHxHEIGHT, qualsiasi altra forma restituirà un errore 400. Tutte le dimensioni (1K / 2K / 4K / personalizzate) vengono addebitate uniformemente per immagine, indipendentemente dalla risoluzione dell’immagine originale e dal valore richiesto per size.
Le restrizioni rigide per le dimensioni personalizzate si applicano anche: larghezza e altezza devono essere multipli di 16, lato lungo ≤ 3840, numero totale di pixel ≤ 8.294.400.
Ad esempio: se l’immagine originale è1024x1024, esizeè2048x2048, il modello ridisegnerà secondo le istruzioni di editing e restituirà un’immagine 2K; sesizeè3840x2160, restituirà un’immagine 4K in orizzontale; se si inviaautoo si omette, il modello sceglierà autonomamente. I costi per tutte e tre le opzioni sono gli stessi.
Riguardo al parametroDi seguito, attraverso due esempi reali da diverse angolazioni, possiamo apprezzare le capacità di editing dinL’interfaccia di editing digpt-image-2attualmente non supportan > 1: questo parametro verrà silenziosamente ignorato, sia che si inviin=1on=10, una singola richiesta restituirà solo 1 immagine e verrà addebitata solo per 1 immagine. Se hai bisogno di ricevere più risultati di editing candidati in una sola volta, devi effettuare più richieste in parallelo. Questa limitazione si applica anche agpt-image-1/gpt-image-1.5, così come alla serienano-banana/nano-banana-2-lite/nano-banana-2/nano-banana-pro.dall-e-2è attualmente l’unico modello di editing che supporta nativamenten > 1.
gpt-image-2.
Metodo di Chiamata 1: JSON + URL Immagine (Consigliato)
Invia direttamente la richiesta in formatoapplication/json, riempiendo il campo image con l’URL di un’immagine, il modello andrà a recuperare quell’immagine e la modificherà secondo il prompt.
Ad esempio, l’immagine originale qui sotto è un’illustrazione scientifica generata con gpt-image-2:


Nota: il campoimagesupporta anche l’inserimento di un array, ad esempio"image": ["url1", "url2", "url3"], fino a un massimo di 16 immagini di riferimento contemporaneamente, consentendo al modello di fare riferimento a più immagini per l’editing.
Invio diretto in base64:image(e ogni elemento dell’array) può essere un URL, ma anche in base64 —data:image/png;base64,...o base64 nudo, adatto per immagini locali che non si desidera caricare su un servizio di hosting. Ad esempio:
Metodo di chiamata due: JSON + più immagini di riferimento
gpt-image-2 supporta il riferimento a più immagini per generare il risultato finale, ad esempio combinando più foto di prodotti in un unico cesto regalo:
Esempio di scenario: cambiare stile + mantenere la struttura
Ecco un altro esempio, sostituendo una libreria in legno con una moderna mensola flottante, ma mantenendo rigorosamente il numero e l’ordine dei libri su ogni ripiano. Immagine originale (libreria in legno generata congpt-image-2):

task_id: e9544dba-727e-44a2-81e1-223d49869380):

Metodo di chiamata tre: multipart/form-data (compatibile con OpenAI SDK)
Se stai già utilizzando l’SDK ufficiale di OpenAI in Python, il metodo di uploadmultipart/form-data esistente è comunque applicabile, basta cambiare model in gpt-image-2:
OPENAI_BASE_URL impostata su https://api.acedata.cloud/openai, e OPENAI_API_KEY impostata sul token ottenuto:
Modelli della serie Nano Banana
La serienano-banana ha integrato anche /openai/images/edits per scenari di editing, basta cambiare model in uno qualsiasi di quelli nella tabella sottostante.
Importante: Intervallo di supporto dei parametri Nano Banana si connette al protocollo OpenAI tramite un layer di adattamento, supporta solo i seguenti parametri:model,prompt,image.
imagepuò essere caricato tramitemultipart/form-data(il worker lo convertirà indata:<mime>;base64,...da inviare all’upstream), oppure può essere passato direttamente come stringa URL dell’immagine tramite un campo del modulo.- Non supporta i parametri
mask,n,size,response_format, ecc.; se forniti, verranno ignorati.- La struttura di ritorno segue il formato OpenAI (
data[].url), macreatedè fisso a0, e non verrà restituitob64_json,revised_promptsarà sempre uguale alpromptoriginale.
Chiamata tramite modulo + URL immagine

Chiamata tramite modulo + file locale
Callback asincrona
Il meccanismo di callbackcallback_url è valido anche per nano-banana, il flusso di chiamata è identico a quello di altri modelli, vedere la sezione Callback asincrona qui sotto.
Utilizzo di base
Ora puoi utilizzare il codice per effettuare la chiamata, qui sotto è un esempio di chiamata tramite CURL:authorization, che può essere selezionato direttamente dal menu a discesa. Un altro parametro è model, model è la categoria del modello OpenAI che scegliamo di utilizzare, qui abbiamo principalmente 1 tipo di modello, i dettagli possono essere visti nei modelli forniti. Un altro parametro è prompt, prompt è il termine che inseriamo per generare l’immagine. L’ultimo parametro è image, questo parametro richiede il percorso dell’immagine da modificare, l’immagine da modificare è mostrata qui sotto:

OPENAI_BASE_URL, che può essere impostata su https://api.acedata.cloud/openai, e l’altra variabile di credenziali OPENAI_API_KEY, il cui valore è ottenuto da authorization, su Mac OS puoi impostare le variabili ambientali con i seguenti comandi:
gift-basket.png nella directory corrente, il risultato specifico è il seguente:

dall-e-2, gpt-image-1 e gpt-image-2, di cui gpt-image-2 è il modello attualmente raccomandato, vedere la sezione Modello GPT-Image-2 sopra.
Callback asincrona
Poiché il tempo di modifica delle immagini dell’API OpenAI Images Edits potrebbe essere relativamente lungo, se l’API non risponde per un lungo periodo, la richiesta HTTP manterrà la connessione, causando un consumo aggiuntivo di risorse di sistema, quindi questa API offre anche supporto per callback asincroni. Il flusso generale è: quando il client invia una richiesta, specifica un campocallback_url aggiuntivo, dopo che il client ha inviato la richiesta API, l’API restituirà immediatamente un risultato, contenente un campo task_id, che rappresenta l’ID del compito corrente. Quando il compito è completato, il risultato della modifica dell’immagine verrà inviato al callback_url specificato dal client in formato JSON POST, che include anche il campo task_id, in modo che il risultato del compito possa essere associato tramite l’ID.
Di seguito vediamo un esempio per capire come operare concretamente.
Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP, gli sviluppatori dovrebbero sostituirlo con l’URL del server HTTP che hanno costruito. Qui, per comodità di dimostrazione, utilizziamo un sito Web pubblico di esempio per Webhook https://webhook.site/, aprendo questo sito si ottiene un URL Webhook, come mostrato nell’immagine:
Copia questo URL, che può essere utilizzato come Webhook, l’esempio qui è https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
Successivamente, possiamo impostare il campo callback_url sull’URL Webhook sopra menzionato, riempiendo i parametri corrispondenti, come mostrato nel seguente codice:
task_id, il campo data contiene lo stesso risultato di editing dell’immagine della chiamata sincrona, e attraverso il campo task_id è possibile realizzare l’associazione del compito.
Gestione degli errori
Quando si chiama l’API, se si incontra un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.500 api_error: Errore interno del server, qualcosa è andato storto sul server.

