Skip to main content
Il servizio di modifica immagini di OpenAI consente di caricare un numero arbitrario di immagini e istruzioni, restituendo immagini modificate. Attualmente l’API supporta contemporaneamente 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-2 supporta 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 size richiedere 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 è 1024x1024 e si passa size = 2048x2048, il modello ridisegnerà e restituirà un’immagine 2K; con size = 3840x2160 restituirà un’immagine 4K orizzontale; con auto o omesso, il modello sceglierà autonomamente. Il costo è identico in tutti e tre i casi.
Nota sul parametro n L’API di modifica gpt-image-2 non supporta n > 1: questo parametro viene ignorato silenziosamente, quindi indipendentemente dal valore di n (es. n=1 o n=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 per gpt-image-1 / gpt-image-1.5 e per la serie nano-banana / nano-banana-2 / nano-banana-pro. Solo dall-e-2 supporta nativamente n > 1 per la modifica.
Di seguito due esempi reali per mostrare le capacità di modifica di gpt-image-2.

Metodo 1: JSON + URL immagine (consigliato)

Invia la richiesta in formato application/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à:
Oppure in Python:
Risposta:
Immagine modificata:

Si nota che la struttura dei moduli, la suddivisione delle informazioni e la tipografia sono state mantenute, invertendo solo lo schema colori in tema scuro.
Suggerimento: il campo image supporta 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 da gpt-image-2):

Chiamata:
Risultato della modifica (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 con multipart/form-data, cambiando solo il modello in gpt-image-2:
Per usare l’SDK devi impostare due variabili d’ambiente: OPENAI_BASE_URL a https://api.acedata.cloud/openai e OPENAI_API_KEY al token ottenuto:

Serie Nano Banana

La serie nano-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.
  • image può essere caricato tramite multipart/form-data (internamente convertito in data:<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), ma created è sempre 0, non viene restituito b64_json e revised_prompt è sempre uguale al prompt originale.

Chiamata con form + URL immagine

Risposta:
Immagine modificata:

Chiamata con form + file locale

Callback asincrono

Il meccanismo di callback asincrono tramite callback_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:
Al primo utilizzo devi fornire almeno quattro parametri: 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:
Per usare Python devi impostare due variabili d’ambiente: OPENAI_BASE_URL a https://api.acedata.cloud/openai e OPENAI_API_KEY al token ottenuto, ad esempio su Mac OS:
Dopo la chiamata, nel percorso corrente verrà generata l’immagine 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 campo callback_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:
La risposta immediata sarà:
Dopo qualche istante, sul webhook vedrai il risultato:
Il campo 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.

Esempio risposta errore

Conclusione

Con questo documento hai appreso come utilizzare OpenAI Images Edits API per sfruttare facilmente la funzionalità ufficiale di modifica immagini di OpenAI. Speriamo che questa guida ti aiuti a integrare e utilizzare al meglio l’API. Per qualsiasi domanda, non esitare a contattare il nostro team di supporto tecnico.