> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API Richiesta e Utilizzo > OpenAI generation 集成指南 - XHuoAPI Il servizio di modifica immagini di OpenAI consente di inviare un numero arbitrario di immagini e istruzioni, restituendo immagini modificate. Attualmente l’API supporta contemporaneamente `dall-e-2`, `gpt-image-1`, l’ultima versione **`gpt-image-2`**, e la serie di modelli **`nano-banana` / `nano-banana-2` / `nano-banana-pro`** integrati tramite la stessa interfaccia. Questo documento descrive principalmente il flusso di utilizzo dell’OpenAI Images Edits API, che permette di sfruttare facilmente le funzionalità ufficiali di editing immagini di OpenAI. ## Procedura di Richiesta Per utilizzare l’OpenAI Images Edits API, puoi innanzitutto visitare la pagina [OpenAI Images Edits API](https://api.xhuoapi.ai/documents/251f1efa-aaa6-462e-8af4-66854b1bc94d) e cliccare sul pulsante «Acquire» per ottenere le credenziali necessarie per le richieste: ![](https://cdn.xhuoapi.ai/nyq0xz.png) Se non hai effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per registrarti o autenticarti; dopo il login verrai riportato automaticamente alla pagina corrente. Alla prima richiesta viene offerto un credito gratuito per utilizzare l’API senza costi. ## Modello GPT-Image-2 `gpt-image-2` offre miglioramenti evidenti rispetto a `gpt-image-1` nel contesto dell’editing immagini: * **Maggiore stabilità strutturale**: nel cambio di skin, colori o sfondo la composizione e il layout originali vengono quasi sempre preservati. * **Maggiore accuratezza nel mantenimento del testo**: immagini con testo come infografiche, poster o menu mantengono il testo chiaro e leggibile dopo la modifica. * **Supporto per URL diretti**: oltre al tradizionale upload 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 richiedere output 2K o 4K tramite il parametro `size`; il modello eseguirà l’editing e l’ingrandimento contemporaneamente. ### Valori supportati per `size` e fasce di prezzo Le restrizioni sul parametro `size` sono identiche a quelle dell’API di generazione: `gpt-image-2` accetta solo valori `auto`, vuoti o nel formato `WIDTHxHEIGHT`; altri formati restituiscono errore 400. Il prezzo dipende solo dal valore di `size`, indipendentemente dalla risoluzione originale: * **Prezzo standard 1K**: qualsiasi dimensione 1K raccomandata nella tabella sottostante, o alias comuni 1K upstream (`1254x1254`, `1672x941`, `941x1672`). * **Altre fasce (1.5×)**: dimensioni 2K / 4K raccomandate o qualsiasi dimensione personalizzata `WIDTHxHEIGHT`. Le restrizioni upstream per dimensioni personalizzate restano valide: larghezza e altezza devono essere multipli di 16, lato lungo ≤ 3840, totale pixel ≤ 8.294.400. | Aspect Ratio | 1K (Prezzo standard) | 2K raccomandato (×1.5) | 4K raccomandato (×1.5) | | ------------ | -------------------- | ---------------------- | ---------------------- | | 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` | > Per esempio: se l’immagine originale è `1024x1024` e `size` è `2048x2048`, il modello ridisegnerà e restituirà un’immagine 2K, con tariffa “altre fasce”; se `size` è `3840x2160`, l’output sarà un’immagine 4K orizzontale, sempre con tariffa “altre fasce”; se `size` è `auto` o omesso, si applica il prezzo standard 1K. > **Nota sul parametro `n`** > > L’API di editing `gpt-image-2` **non supporta `n > 1`**: questo parametro viene ignorato silenziosamente e indipendentemente dal valore (es. `n=1` o `n=10`), ogni richiesta restituisce una sola immagine e viene fatturata come una sola. Per ottenere più risultati in un’unica sessione, occorre inviare più richieste concorrenti. Questa limitazione vale anche per `gpt-image-1` / `gpt-image-1.5` e la serie `nano-banana`. Solo `dall-e-2` supporta nativamente `n > 1` per l’editing. Di seguito due esempi reali da diverse prospettive per mostrare le capacità di editing 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, l’immagine originale qui sotto è un’infografica generata con `gpt-image-2`:

Vogliamo convertirla in modalità “notte”. La chiamata sarà: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/v1/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/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 esattamente, solo lo schema cromatico è stato invertito in tema scuro. > **Suggerimento**: il campo `image` supporta anche un array, ad esempio `"image": ["url1", "url2", "url3"]`, fino a 16 immagini di riferimento, permettendo al modello di considerare più immagini contemporaneamente. ### Metodo 2: JSON + più immagini di riferimento `gpt-image-2` supporta l’uso simultaneo di più immagini di riferimento per generare il risultato finale, 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 di scenario: cambio stile mantenendo struttura Ecco un altro esempio: sostituire una libreria in legno con una mensola moderna sospesa, mantenendo esattamente il numero e la disposizione dei libri per ogni ripiano. Immagine originale (libreria in legno generata con `gpt-image-2`):

Chiamata: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/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 dell’editing (`task_id`: `e9544dba-727e-44a2-81e1-223d49869380`):

Si osserva che stile e ambiente sono stati completamente modificati secondo il prompt, ma il numero di libri per ripiano (1 / 3 / 7) è stato rigorosamente mantenuto, e sulla mensola superiore è stata aggiunta una piccola pianta grassa come richiesto. ### Metodo 3: multipart/form-data (compatibile con OpenAI SDK) Se usi già l’OpenAI Python SDK ufficiale, puoi continuare a caricare i file con `multipart/form-data`, basta cambiare 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) ``` Quando usi l’SDK devi impostare due variabili d’ambiente: `OPENAI_BASE_URL` a `https://api.xhuoapi.ai/v1/openai` e `OPENAI_API_KEY` al token ottenuto: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` ## Serie Nano Banana La serie `nano-banana` è integrata nell’endpoint `/openai/images/edits`; basta impostare `model` su uno dei valori della tabella seguente. | Modello | Costo (Crediti / chiamata) | Scenario d’uso | | ----------------- | -------------------------- | ---------------------------------------------------------------- | | `nano-banana` | 0.14 | Editing immagini standard, velocità massima e costo minimo | | `nano-banana-2` | 0.28 | Qualità e dettaglio migliorati | | `nano-banana-pro` | 0.35 | Top di gamma, migliore conservazione di struttura, testo e stile | > **Importante: parametri supportati** > > Nano Banana usa un layer di adattamento per aderire al protocollo OpenAI, supportando 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 stringa nel form. > * Non sono supportati parametri come `mask`, `n`, `size`, `response_format`; se forniti vengono ignorati. > * La risposta segue il formato OpenAI (`data[].url`), ma `created` è sempre `0`, non viene restituito `b64_json` e `revised_prompt` è identico al prompt originale. ### Chiamata con form + URL immagine ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Risposta: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/v1/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 lo stesso flusso degli altri modelli, come descritto nella sezione [Callback asincrono](#callback-asincrono). ## Utilizzo base Ora puoi effettuare chiamate tramite codice; qui sotto un esempio 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.xhuoapi.ai/v1/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 dell’API, devi fornire almeno quattro elementi: `authorization` (selezionabile dal menu a tendina), `model` (scegli il modello OpenAI, qui principalmente uno, vedi i modelli disponibili), `prompt` (la descrizione per generare l’immagine) e `image` (il percorso dell’immagine da modificare). L’immagine da modificare è 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.xhuoapi.ai/v1/openai` e `OPENAI_API_KEY` al token ottenuto da `authorization`. Su Mac OS puoi impostarle così: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` Dopo la chiamata, vedrai un’immagine `gift-basket.png` nella cartella corrente, come mostrato:

Così hai completato l’operazione di editing. Attualmente l’API Edits supporta tre modelli: `dall-e-2`, `gpt-image-1` e `gpt-image-2`, con `gpt-image-2` come modello consigliato, vedi la sezione [Modello GPT-Image-2](#modello-gpt-image-2). ## Callback asincrono Poiché l’editing immagini con OpenAI Images Edits API può richiedere tempo, mantenere la connessione HTTP aperta per lunghi periodi consuma risorse di sistema. Per questo 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. Quando il task è completato, il risultato dell’editing viene inviato tramite POST JSON all’URL specificato in `callback_url`, includendo anche il `task_id` per correlare la risposta. Ecco un esempio pratico. Un webhook è un servizio HTTP che riceve richieste; devi sostituire l’URL con il tuo server HTTP. Per demo usiamo il sito pubblico [https://webhook.site/](https://webhook.site/), che genera un URL webhook come mostrato: ![](https://cdn.xhuoapi.ai/cjjfly.png) Copia questo URL, ad esempio `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. Poi invia la richiesta con il campo `callback_url` impostato a questo URL, come nel codice seguente: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/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 dell’editing: ```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..." } ] } } ``` Si nota il campo `task_id` e il campo `data` con il risultato dell’editing, uguale a quello della chiamata sincrona, permettendo di associare i risultati tramite ID. ## Gestione errori Se si verifica un errore durante la chiamata all’API, questa restituisce un codice e un messaggio di errore. Alcuni esempi: * `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 di autorizzazione mancante o non valido. * `429 too_many_requests`: troppe richieste, superato il limite di velocità. * `500 api_error`: errore interno del server. ### Esempio di risposta errore ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusioni Con questo documento hai appreso come utilizzare facilmente l’OpenAI Images Edits API per sfruttare le funzionalità ufficiali di editing immagini di OpenAI. Speriamo che questa guida ti aiuti a integrare e usare al meglio l’API. Per qualsiasi domanda, non esitare a contattare il nostro team di supporto tecnico.