Skip to main content
Il servizio di editing delle immagini di OpenAI consente di inviare un numero qualsiasi di immagini e istruzioni, restituendo le immagini modificate. Attualmente, l’interfaccia supporta contemporaneamente 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-2 supporta 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 image può 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. Supporta n > 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 di gpt-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 al gpt-image-2 di 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:official supporta n > 1 e 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, e size è 2048x2048, il modello ridisegnerà secondo le istruzioni di editing e restituirà un’immagine 2K; se size è 3840x2160, restituirà un’immagine 4K in orizzontale; se si invia auto o si omette, il modello sceglierà autonomamente. I costi per tutte e tre le opzioni sono gli stessi.
Riguardo al parametro n L’interfaccia di editing di gpt-image-2 attualmente non supporta n > 1: questo parametro verrà silenziosamente ignorato, sia che si invii n=1 o n=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 a gpt-image-1 / gpt-image-1.5, così come alla serie nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro. dall-e-2 è attualmente l’unico modello di editing che supporta nativamente n > 1.
Di seguito, attraverso due esempi reali da diverse angolazioni, possiamo apprezzare le capacità di editing di gpt-image-2.

Metodo di Chiamata 1: JSON + URL Immagine (Consigliato)

Invia direttamente la richiesta in formato application/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:

Desideriamo cambiarla in una colorazione “modalità notturna”. Possiamo chiamarla in questo modo:
Oppure usa Python:
Il risultato restituito è il seguente:
L’immagine modificata è la seguente:

Si può notare che la struttura dei moduli, la suddivisione delle informazioni e la tipografia sono state rigorosamente mantenute, solo la combinazione di colori è stata invertita in un tema scuro.
Nota: il campo image supporta 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 con gpt-image-2):

Chiamata:
Risultato dell’editing (task_id: e9544dba-727e-44a2-81e1-223d49869380):

Si può notare che lo stile e l’ambiente sono stati completamente sostituiti secondo le istruzioni, ma il numero di libri su ogni ripiano (1 / 3 / 7) è rimasto rigorosamente mantenuto, e come richiesto è stata aggiunta una piccola pianta grassa.

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 upload multipart/form-data esistente è comunque applicabile, basta cambiare model in gpt-image-2:
Quando si utilizza l’SDK, è necessario prima importare due variabili ambientali, OPENAI_BASE_URL impostata su https://api.acedata.cloud/openai, e OPENAI_API_KEY impostata sul token ottenuto:

Modelli della serie Nano Banana

La serie nano-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.
  • image può essere caricato tramite multipart/form-data (il worker lo convertirà in data:<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), ma created è fisso a 0, e non verrà restituito b64_json, revised_prompt sarà sempre uguale al prompt originale.

Chiamata tramite modulo + URL immagine

Il risultato restituito è il seguente:
Immagine modificata:

Chiamata tramite modulo + file locale

Callback asincrona

Il meccanismo di callback callback_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:
Quando utilizzi per la prima volta questa interfaccia, è necessario compilare almeno quattro contenuti, uno è 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:

Esempio di codice di chiamata Python con lo stesso effetto:
Per utilizzare Python, dobbiamo prima importare due variabili ambientali, una 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:
Dopo la chiamata, noteremo che verrà generata un’immagine gift-basket.png nella directory corrente, il risultato specifico è il seguente:

Così abbiamo completato l’operazione di modifica dell’immagine, attualmente l’interfaccia Edits supporta tre modelli: 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 campo callback_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:
Dopo la chiamata, possiamo notare che si ottiene immediatamente un risultato, come segue:
Aspettando un momento, possiamo osservare il risultato dell’editing dell’immagine sull’URL Webhook, il contenuto è il seguente:
Possiamo vedere che nel risultato c’è un campo 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.

Esempio di risposta di errore

Conclusione

Attraverso questo documento, hai appreso come utilizzare facilmente l’API OpenAI Images Edits per sfruttare le funzionalità di editing delle immagini ufficiali di OpenAI. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.