OpenAI Images Edits API Richiesta e Utilizzo

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 e cliccare sul pulsante «Acquire» per ottenere le credenziali necessarie per le richieste:

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à:

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:

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:

{
  "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:

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:

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:

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:

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:<mime>;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

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:

{
  "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

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.

Utilizzo base

Ora puoi effettuare chiamate tramite codice; qui sotto un esempio con CURL:

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[][email protected]" \
  -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:

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ì:

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.

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/, che genera un URL webhook come mostrato:

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:

curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -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à:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

Dopo qualche istante, sul webhook vedrai il risultato dell’editing:

{
  "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

{
  "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.

Documentation Index

​Procedura di Richiesta

​Modello GPT-Image-2

​Valori supportati per size e fasce di prezzo

​Metodo 1: JSON + URL immagine (consigliato)

​Metodo 2: JSON + più immagini di riferimento

​Esempio di scenario: cambio stile mantenendo struttura

​Metodo 3: multipart/form-data (compatibile con OpenAI SDK)

​Serie Nano Banana

​Chiamata con form + URL immagine

​Chiamata con form + file locale

​Callback asincrono

​Utilizzo base

​Callback asincrono

​Gestione errori

​Esempio di risposta errore

​Conclusioni

Procedura di Richiesta

Modello GPT-Image-2

Valori supportati per `size` e fasce di prezzo

Metodo 1: JSON + URL immagine (consigliato)

Metodo 2: JSON + più immagini di riferimento

Esempio di scenario: cambio stile mantenendo struttura

Metodo 3: multipart/form-data (compatibile con OpenAI SDK)

Serie Nano Banana

Chiamata con form + URL immagine

Chiamata con form + file locale

Callback asincrono

Utilizzo base

Callback asincrono

Gestione errori

Esempio di risposta errore

Conclusioni