> ## Documentation Index > Fetch the complete documentation index at: https://germeytechnology-docs-remove-4o-image-nav.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API Richiesta e Utilizzo > OpenAI generation 集成指南 - Ace Data Cloud 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](https://platform.acedata.cloud/documents/openai-images-edits) e cliccare sul pulsante “Acquire” per ottenere le credenziali necessarie per la richiesta: ![](https://cdn.acedata.cloud/nyq0xz.png) 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. | Rapporto | Consigliato 1K | Consigliato 2K | Consigliato 4K | | -------- | -------------- | -------------- | -------------- | | 1:1 | `1024x1024` | `2048x2048` | `2880x2880` | | 4:3 | `1536x1024` | `2048x1536` | `3264x2448` | | 3:4 | `1024x1536` | `1536x2048` | `2448x3264` | | 16:9 | `1792x1024` | `2048x1152` | `3840x2160` | | 9:16 | `1024x1792` | `1152x2048` | `2160x3840` | > 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à: ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" }' ``` Oppure in Python: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Risposta: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` 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: ```python theme={null} payload = { "model": "gpt-image-2", "image": [ "https://example.com/item1.png", "https://example.com/item2.png", "https://example.com/item3.png" ], "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.", "size": "1024x1024" } ``` ### 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: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.", "size": "1024x1024" } ``` 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`: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() result = client.images.edit( model="gpt-image-2", image=[open("test.png", "rb")], prompt="Convert this image to dark mode while keeping the layout intact." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` 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: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` ## 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. | Modello | Costo (Crediti / chiamata) | Scenario d’uso | | ----------------- | -------------------------- | ---------------------------------------------------------------- | | `nano-banana` | 0.14 | Modifica immagini generica, più veloce e a costo minimo | | `nano-banana-2` | 0.28 | Qualità e dettagli migliorati | | `nano-banana-pro` | 0.35 | Top di gamma, migliore conservazione di struttura, testo e stile | > **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:;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 ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=add a green leaf on top of the apple" \ -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Risposta: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "add a green leaf on top of the apple" } ] } ``` Immagine modificata:

### Chiamata con form + file locale ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "authorization": "Bearer {token}" } files = { "image": open("apple.png", "rb"), } data = { "model": "nano-banana-pro", "prompt": "add a green leaf on top of the apple" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### 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](#callback-asincrono). ## Uso base Ecco un esempio di chiamata con CURL: ```curl theme={null} curl -s -D >(grep -i x-request-id >&2) \ -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F 'prompt=Create a lovely gift basket with these this items in it' ``` 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: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Generate a photorealistic image of a gift basket on a white background labeled 'Relax & Unwind' with a ribbon and handwriting-like font, containing all the items in the reference pictures. """ result = client.images.edit( model="gpt-image-1", image=[ open("test.png", "rb") ], prompt=prompt ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) # Salva l’immagine su file with open("gift-basket.png", "wb") as f: f.write(image_bytes) ``` 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: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` 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](#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/](https://webhook.site/), che fornisce un URL webhook come mostrato: ![](https://cdn.acedata.cloud/cjjfly.png) Copia l’URL, ad esempio `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`, e usalo come `callback_url` nella richiesta: ```shell theme={null} curl -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Create a lovely gift basket with these items in it" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` La risposta immediata sarà: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Dopo qualche istante, sul webhook vedrai il risultato: ```json theme={null} { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": { "created": 1721626477, "data": [ { "b64_json": "iVBORw0KGgo..." } ] } } ``` 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 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 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.