L'API di modifica delle immagini OpenAI modifica un'immagine esistente in base a un prompt. Il percorso nativo è POST /v1/images/edits; accetta un'immagine, un prompt e controlli di modifica opzionali, come una maschera o immagini di riferimento. Utilizza l'API Image per una richiesta mirata e l'API Responses quando il prodotto richiede un flusso di lavoro con immagini a più passaggi.
Una modifica affidabile è un processo semplice: bloccare il file sorgente, specificare cosa deve rimanere invariato e cosa può essere modificato, controllare i byte restituiti e salvare la risorsa approvata. Se si preferisce passare da un modello di immagine all’altro e utilizzare altri strumenti multimediali all’interno di un unico spazio di lavoro, creare e modificare immagini con GPT Image 2 in GlobalGPT; la sua API pubblica utilizza un contratto di attività asincrona diverso, che questa guida distingue dall’endpoint nativo di OpenAI.
Risposta breve: scegli il percorso prima di scrivere il codice
| Necessità | Percorso | Richiesta forma | Risultato da gestire |
|---|---|---|---|
| Una generazione o modifica di immagine | API immagine OpenAI | POST /v1/images/edits, modulo in più parti | data[0].b64_json; decodificarlo e salvarlo |
| Diverse iterazioni con il contesto dell'immagine | API delle risposte OpenAI | POST /v1/responses con uno strumento per la generazione di immagini | Estrai l'elemento di output relativo alla generazione dell'immagine |
| Diversi profili social associati a un unico account | API pubblica GlobalGPT | POST /tasks, quindi eseguire il polling GET /tasks/{id} | output.url; salvalo prima che scada il termine di 30 giorni |
I nomi degli endpoint sembrano simili, ma i corpi delle richieste e la gestione dei risultati non sono intercambiabili.
Cosa fa l'API di modifica delle immagini OpenAI?
Il percorso di modifica parte da un'immagine esistente. Il prompt descrive la modifica, mentre l'immagine di input fornisce il contesto visivo che deve rimanere invariato durante la modifica. È possibile sostituire uno sfondo, aggiungere o rimuovere un elemento, apportare una modifica stilistica più ampia oppure fornire più immagini come riferimento. Il modello continua a interpretare la richiesta; l'API non è un editor di pixel con un contorno di selezione garantito.
OpenAI descrive due flussi di lavoro utili. Il API Immagini è la scelta più ovvia quando una richiesta deve restituire una sola immagine. Il API delle risposte è la soluzione più adatta quando un utente esamina il risultato, richiede un'altra modifica e mantiene il contesto dell'immagine tra un turno e l'altro. Questa scelta influisce sia sulla struttura della richiesta sia sul codice che estrae il risultato.
API Immagini contro API Risposte
| Domanda | API Immagini | API delle risposte |
|---|---|---|
| Il migliore per | Una singola azione di creazione o modifica | Un'esperienza di editing a più fasi |
| Dati di input tipici | Immagine composta da più parti, prompt, maschera facoltativa | Strumento per l'inserimento di conversazioni e la generazione di immagini |
| Gestione dell'output | data[0].b64_json | Individuare la voce relativa alla generazione delle immagini |
| Dettagli sui costi | La modifica diretta utilizza le frequenze di input/output correnti | Le regole di inserimento salvate nella cache potrebbero variare; verificare i prezzi attuali |
Effettua una prima modifica utilizzando l'API nativa OpenAI
Conserva la chiave API sul tuo server e caricala da una variabile d’ambiente. L’esempio riportato di seguito invia un’immagine e un prompt all’endpoint "edits" documentato. Il immagine[] Il campo può essere ripetuto quando il modello selezionato supporta più input. La pipeline della shell decodifica la prima immagine in formato base64 restituita in un file PNG locale.
Modifica Native Curl: salvare il risultato in formato b64_json
curl -s \
-X POST "https://api.openai.com/v1/images/edits" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F "model=gpt-image-2.5-sunburst" \
-F "image[]=@source.png" \
-F "prompt=Sostituisci solo lo sfondo con una scena da studio in beige caldo; mantieni invariati il prodotto e l'etichetta." \
| jq -r '.data[0].b64_json' \
| base64 --decode > edited.pngModifica dell'SDK Python: decodifica dei byte restituiti
da openai import OpenAI
import base64
client = OpenAI()
result = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open("source.png", "rb"),
prompt="Sostituisci solo lo sfondo con una scena da studio in tonalità beige caldo; mantieni invariati il prodotto e l'etichetta.",
)
image_bytes = base64.b64decode(result.data[0].b64_json)
with open("edited.png", "wb") as output:
output.write(image_bytes)Prima di considerare questa versione pronta per la produzione, verifica il file decodificato: controlla il tipo MIME, le dimensioni, il numero di byte e se i dettagli visivi rilevanti sono ancora presenti. Una risposta 200 indica solo che la richiesta è stata accettata; non garantisce che l'etichetta, il logo o la geometria del prodotto siano stati conservati.
Utilizzare le maschere e le immagini di riferimento in modo sicuro
Una maschera indica al modello quale area si desidera modificare, ma la funzione di mascheramento di GPT Image rimane basata sui prompt. La guida di OpenAI avverte esplicitamente che il modello utilizza la maschera come indicazione piuttosto che come confine assoluto in termini di pixel. Assicurati che il prompt sia specifico riguardo al soggetto da proteggere e controlla l’intera immagine dopo la generazione.
Controllo preliminare della maschera
- L'immagine e la maschera utilizzano lo stesso formato.
- L'immagine e la maschera hanno le stesse dimensioni.
- Il file della maschera è inferiore a 50 MB.
- La maschera contiene un canale alfa.
- Il prompt indica cosa deve rimanere invariato e cosa va sostituito.
Controlla la maschera prima di caricarla
da PIL import Image
source = Image.open("source.png")
mask = Image.open("mask.png")
assert source.format == mask.format, (source.format, mask.format)
assert source.size == mask.size, (source.size, mask.size)
assert mask.width * mask.height > 0
assert mask.mode in {"RGBA", "LA"}, mask.mode
assert mask.fp is None or True # verificare separatamente la dimensione del file su disco
print("source:", source.size, source.format)
stampa("maschera:", mask.size, mask.mode)Se si inseriscono più immagini con una maschera, secondo le linee guida attuali la maschera si applica alla prima immagine. Si tratta di un criterio utile per definire un flusso di lavoro di riferimento: impostare come primo input l’elemento di cui si intende modificare l’area e considerare le immagini rimanenti come riferimenti, anziché dare per scontato che la maschera selezioni tutte le immagini.
Le immagini di riferimento risolvono un problema diverso. Possono fornire un’identità al prodotto, una famiglia di luci, una tavolozza o un suggerimento compositivo. Non impongono al modello di mantenere ogni singolo contorno. Se la forma esatta di una confezione o di un’etichetta deve rimanere invariata, è opportuno ricorrere a una fase di revisione visiva o a un’operazione di modifica convenzionale dopo la generazione del modello.
Scegli il modello e i parametri
L'attuale elenco delle guide per immagini OpenAI riporta gpt-immagine-2.5-sunburst, gpt-image-2.5-flare, e gpt-immagine-2. Considera i nomi dei modelli e le opzioni supportate come documentazione in continua evoluzione: controlla la pagina del modello immediatamente prima di integrarli e salva una versione datata se la riproducibilità è importante.
Decisioni relative ai parametri che consentono di prevenire guasti evitabili
| Decisione | Regola pratica | Perché è importante |
|---|---|---|
| Fedeltà dell'input | Ometti fedeltà_d'ingresso per gpt-immagine-2; i dati di immagine in ingresso vengono elaborati con un'elevata fedeltà. | L'invio di un campo non supportato può trasformare una modifica valida in una richiesta respinta. |
| Qualità | Il documento relativo ai percorsi "2.5 Sunburst" e "Flare" basso, medio, alto, xhigh, e max. | Un valore più alto comporta una scelta tra costo e latenza, non una garanzia di una migliore conservazione. |
| Formato | Richiedi il formato di output specificato dall'endpoint corrente, quindi esamina il file decodificato. | La tua pipeline di archiviazione dovrebbe basarsi sui byte e sul tipo MIME, non solo sull'opzione richiesta. |
| Contesto | Specificare lo sfondo desiderato nel prompt e utilizzare l'opzione "sfondo" documentata, ove supportata. | Il modello continua a interpretare la scena; mantieni espliciti i vincoli relativi al soggetto. |
| Riferimenti | Utilizza un'immagine di riferimento come guida per l'identità visiva, i colori o l'illuminazione e definisci la funzione di ogni elemento. | I ruoli ambigui delle immagini rendono più difficile individuare eventuali scostamenti. |
Quanto costa l'API di modifica delle immagini OpenAI?
OpenAI applica tariffe per l'utilizzo di GPT Image in base alle categorie di token, anziché a un prezzo forfettario unico per ogni modifica. L'attuale pagina dei prezzi riporta tariffe distinte per input di immagini, input da cache e output di immagini. Le modifiche effettuate tramite l’API Direct Image non beneficiano del trattamento relativo agli input memorizzati nella cache documentato per lo strumento di generazione delle immagini nell’API Responses; pertanto, non copiare una stima dell’API Responses in un’API Direct /v1/immagini/modifiche bilancio.
Tariffe dei token immagine pubblicate, verificate il 28 settembre 2026
| Modello | Input immagine / 1 milione di token | Immagine memorizzata nella cache / 1 milione di token | Output immagine / 1 milione di token |
|---|---|---|---|
| GPT Image 2.5 | $8 | $2* | $30 |
| Immagine GPT 2 | $4 | $1* | $15 |
*La colonna “cached-input” viene visualizzata per il contesto tariffario pubblicato. La guida alle tariffe precisa che l’input memorizzato nella cache si applica allo strumento di generazione delle immagini nell’API Responses, non alle richieste dirette all’API Images, come ad esempio /v1/immagini/modifiche. Le tariffe possono variare; effettua il calcolo in base ai dati di utilizzo riportati nella tua richiesta.
Elaborare una stima trasparente sulla base dei dati di utilizzo
def stima_costo_immagine(token_immagine_input, token_immagine_output,
tasso_input, tasso_output):
return (image_input_tokens / 1_000_000) * input_rate + \
(image_output_tokens / 1_000_000) * output_rate
# Solo a titolo di esempio: sostituisci con l'utilizzo nella tua risposta.
estimate = estimate_image_cost(
image_input_tokens=250_000,
image_output_tokens=120_000,
input_rate=4.00,
output_rate=15.00,
)
print(f"${estimate:.4f}")Questa formula è un esempio di pianificazione, non una garanzia di un costo fisso per immagine. Includete nel vostro budget i tentativi successivi, l'archiviazione dei file ed eventuali costi aggiuntivi per l'utilizzo di testi o strumenti. Quando il risultato è importante, tenete insieme la richiesta, l'utilizzo della risposta, l'hash del file decodificato e la decisione di approvazione.
GlobalGPT utilizza un contratto API di modifica delle immagini diverso
Il Documentazione API GlobalGPT descrive la generazione di immagini, video e audio come attività multimediali asincrone. Il suo URL di base pubblico è https://api2.glbgpt.com/ai-api/open/v1. Invia il file JSON a /attività, sondaggio /tasks/{id}, e leggi output.url al termine di un'attività completata con successo. Il catalogo dei modelli elenca gpt-immagine-2 e gpt-image-2.5 come percorsi di modifica/riferimento delle immagini con un massimo di quattro immagini di input e rapporto di aspetto.
Documentazione dell'API pubblica S05: Documentazione pubblica relativa al contratto per le attività asincrone; questo articolo lo distingue dall’endpoint nativo di OpenAI per le modifiche multiparte.
Catalogo dei modelli pubblici della serie S06: Prove pubbliche tratte dal catalogo dei modelli relative ai percorsi GPT Image e ai relativi limiti documentati per le attività relative alle immagini; verificare i crediti e i campi dinamici prima della pubblicazione.
Forma dell'attività pubblica GlobalGPT
BASE="https://api2.glbgpt.com/ai-api/open/v1"
# Opzionale: stima senza creare un'attività o riservare crediti.
curl "$BASE/tasks/estimate" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5",
"prompt": "Mantieni invariati la bottiglia e l'etichetta. Sostituisci solo lo sfondo con una calda illuminazione da studio color beige.",
"images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
"aspect_ratio": "3:2"
}'
# Invia solo dopo aver verificato il preventivo.
curl "$BASE/tasks" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: image-edit-example-001" \
-d '{
"model": "gpt-image-2.5",
"prompt": "Mantieni invariate la bottiglia e l’etichetta. Sostituisci solo lo sfondo con una calda illuminazione da studio beige.",
"images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
"aspect_ratio": "3:2"
}'
# Interroga l’ID dell’attività restituito fino a quando non si ottiene un esito positivo o negativo.
curl "$BASE/tasks/TASK_ID" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY"Non incollare il file multipart di OpenAI maschera, fedeltà_d'ingresso, dimensione, o qualità campi in questo JSON e supponiamo che funzionino. L'attuale documentazione pubblica relativa a GlobalGPT non elenca tali campi per questa rotta di immagine. I campi non supportati potrebbero essere ignorati e riportati in parametri_ignorati, quindi controlla quella risposta prima di concludere che un'impostazione sia stata applicata.
GlobalGPT riserva i crediti quando viene inviata un'attività multimediale, li libera quando l'attività fallisce e mantiene disponibili i contenuti multimediali riusciti per 30 giorni, secondo la documentazione pubblica. Salva la risorsa restituita su uno spazio di archiviazione di tua gestione se l'URL deve rimanere attivo più a lungo. Utilizza l’endpoint di stima prima di un’elaborazione in batch, una chiave di idempotenza quando riprovi a inviare una richiesta di rete e l’ID originale dell’attività quando il polling è semplicemente lento.
Cosa ha evidenziato il test sul modello GlobalGPT
Per rendere concreta questa distinzione, il 28 settembre 2026 ho eseguito un test API su un modello GlobalGPT con vincoli, utilizzando due prompt di input fittizi e senza riferimenti a marchi e due prompt di modifica. Ogni attività ha utilizzato GPT Image 2, una richiesta 3:2 e il primo output valido. Le immagini riportate di seguito sono prove del test del modello, non una sessione dell’area di lavoro del browser, un benchmark o una garanzia che ogni modifica preserverà ogni contorno.
Dati di ingresso P00: L'immagine originale congelata: una bottiglia immaginaria senza marchio, con un tappo bianco corto e un'etichetta corta.
Riferimento P01: L'immagine di riferimento "congelata": utilizzata esclusivamente per l'illuminazione e il colore, non come seconda identità del prodotto.
T01: modifica dello sfondo di una singola immagine
Mostra il prompt completo
Mantieni invariati la bottiglia in ceramica, il tappo bianco corto, il testo fittizio dell’etichetta "NORTH" e "250 ml", i colori, l’angolazione della fotocamera e le proporzioni dell’immagine di partenza. Sostituisci solo lo sfondo bianco puro con un ambiente da studio interno dai toni beige caldi, ispirato alla luce soffusa che entra dalla finestra e alle ombre delicate. Non aggiungere alcun nuovo oggetto, logo, parola, filigrana, persona o etichetta. Mantieni la bottiglia come unico soggetto in una composizione orizzontale con rapporto 3:2.
Ciò dimostra che: La bottiglia rimane riconoscibile, l’etichetta NORTH / 250 ml è visibile e lo sfondo bianco si trasforma in una scena d’interni dai toni caldi del beige, con morbide ombre simili a quelle proiettate da una finestra.
Limite: Questo è un primo risultato valido. Non dimostra però la conservazione esatta dei pixel né la fedeltà generale delle etichette.
T02: riferimento per l’illuminazione e il colore basato su due immagini
Mostra il prompt completo
Utilizza l'immagine di input 1 come riferimento esatto per il prodotto e l'immagine di input 2 solo come riferimento per l'illuminazione beige calda, la temperatura di colore e le ombre morbide dell'ambiente interno. Mantieni invariati la forma della bottiglia in ceramica, il tappo bianco corto, il testo fittizio dell'etichetta "NORTH" e "250 ml", i colori, l'angolazione della fotocamera e le proporzioni dell'immagine di input 1. Sostituisci lo sfondo bianco con una tranquilla scena da studio in interni dai toni beige caldi. Non copiare alcun oggetto, testo, logo, filigrana, persona o etichetta aggiuntivi dall’immagine di input 2. Mantieni la bottiglia come unico soggetto in una composizione orizzontale 3:2.
Ciò dimostra che: Il prodotto e l’etichetta NORTH / 250 ml rimangono riconoscibili, mentre l’ambientazione riprende l’atmosfera calda del beige della stanza, del tavolo e della luce che entra dalla finestra tipica del modello P01.
Limite: Le proporzioni del tappo, il profilo della bottiglia e la posizione sono cambiati in modo evidente. Non consideratela una conservazione perfetta o esatta dell'identità; ricorrete al confronto manuale quando le dimensioni della merce devono corrispondere.
Come utilizzare questi dati: Il risultato utile è un processo di revisione ripetibile. Bloccare l’URL di input, denominare l’oggetto protetto, descrivere il ruolo di riferimento, ispezionare i byte restituiti e confrontare il prodotto approvato con la fonte prima della pubblicazione. Il trasferimento dello stile può avere esito positivo anche se la geometria continua a subire variazioni.
Gestire gli errori e le risposte lente
Sintomo → verifica → azione
| Sintomo | Controlla prima | Il prossimo passo sicuro |
|---|---|---|
| 401 / errore di autenticazione | Chiave lato server, autorizzazioni dell'account, host dell'endpoint | Interrompi e correggi l'autenticazione; non valutare la qualità dell'immagine. |
| 400 / 422 richiesta non valida | ID modello, nomi dei campi composti, tipo di file, opzioni non supportate | Modifica solo il campo indicato nell'errore, quindi mantieni la richiesta originale che ha generato l'errore. |
| 429 / 5xx / capacità | Se è stato creato un ID attività | Se non esiste alcun ID attività, riprova una volta in base alla tua politica; se esiste un’attività, esegui il polling su quell’ID. |
| L'attività rimane in coda o in elaborazione | Stato, ora dell'ultimo sondaggio, stima del fornitore | Eseguire il polling a intervalli prestabiliti; non creare duplicati finché lo stato è sconosciuto. |
| L'output è un oggetto JSON salvato come immagine | Tipo di contenuto, primi byte, formato decodificato | Analizza la risposta, decodifica b64_json oppure scarica output.url, quindi convalidare. |
| Il parametro sembra non avere alcun effetto | GlobalGPT parametri_ignorati e scheda del modello | Rimuovere i campi non supportati e utilizzare il contratto specifico del modello. |
Distinguere le prove relative al trasporto da quelle relative alla qualità. Un timeout, un errore DNS o una risposta relativa alla capacità del provider indicano che non si dispone di un'immagine valida da valutare. Al contrario, un'immagine valida con un limite o un'etichetta modificati costituisce un risultato visivo che deve essere riportato così com'è, anche se la composizione appare accattivante.
Una lista di controllo per la modifica delle immagini in ambiente di produzione
- Blocca la sorgente: salvare il file di input, le dimensioni, il formato e l'hash.
- Assegnare i ruoli alle immagini: identificare l'immagine in questione ed eventuali riferimenti relativi all'illuminazione, alla tavolozza dei colori o alla composizione.
- Cue protetti da scrittura: Elenca l'etichetta, la silhouette, i colori e le proporzioni che devono essere rivisti.
- Scegli il contratto: utilizzare il formato multipart OpenAI per l'endpoint "native edits" oppure le operazioni JSON GlobalGPT per la sua API multimediale pubblica.
- Calcolare e inviare: utilizzare le tariffe attuali OpenAI o GlobalGPT
/attività/preventivo; aggiungere una chiave di idempotenza per garantire la sicurezza dei tentativi ripetuti. - Raccolta dati e decodifica: conservare un ID attività, verificare la validità del file restituito e salvare i byte o l'URL in un archivio autorizzato.
- Approvare visivamente: confrontare il risultato con il testo originale prima che venga inserito in un catalogo prodotti, in un annuncio pubblicitario o in una pagina destinata ai clienti.
Se vuoi eseguire lo stesso processo senza dover unire dashboard di modelli separati, prova a Immagine GPT 2 in GlobalGPT. Per la versione del flusso di lavoro pensata per i browser, consultare modifica le immagini nell'area di lavoro GlobalGPT; per un'analisi più approfondita delle configurazioni e dei prezzi, si veda Configurazione e prezzi dell'API GPT Image.
Domande frequenti
Che cos’è l’API OpenAI per l’editing delle immagini?
Si tratta del percorso di modifica delle immagini all'indirizzo POST /v1/images/edits. Si inviano un'immagine di input e un prompt, facoltativamente accompagnati da una maschera o da immagini di riferimento, quindi si decodificano i dati dell'immagine restituiti. Utilizzare l'API Immagini per una singola modifica e l'API Risposte quando il prodotto richiede una conversazione in più fasi sull'immagine.
L'API di modifica delle immagini OpenAI restituisce un URL pubblico dell'immagine?
Gli esempi documentati dell'API Image restituiscono dati in formato b64_json. Decodifica quei byte, verifica la validità del file e salvalo in uno spazio di archiviazione di tua scelta. Non dare per scontato che una risposta positiva corrisponda a un URL CDN ospitato.
La maschera di immagine OpenAI corrisponde a una selezione esatta dei pixel?
No. Una maschera guida una modifica basata su prompt. Il modello può modificare i pixel intorno all’area richiesta, quindi controlla le etichette, i dettagli del prodotto, i simboli di sicurezza e altri elementi che devono rimanere corretti.
Quante immagini di input può utilizzare un programma di editing delle immagini?
La guida alle immagini attuale supporta più immagini di input per i flussi di lavoro di riferimento. Per conoscere il limite esatto e il comportamento specifico del modello, consultare la documentazione del modello in uso; il numero massimo supportato non garantisce una conservazione perfetta in ogni composizione.
Posso inviare la richiesta OpenAI /v1/images/edits a GlobalGPT modificando il valore di base_url?
Il contratto multimediale pubblico di GlobalGPT utilizza JSON POST /tasks, seguito da GET /tasks/{id}, con immagini e aspect_ratio laddove il modello selezionato li accetti. La documentazione pubblica non riporta la maschera multipart, il parametro `input_fidelity`, le dimensioni né il contratto di qualità di OpenAI per quella route.
Come devo valutare un compito relativo alle immagini prima di inviarlo?
Per GlobalGPT, inviare innanzitutto lo stesso corpo JSON a /tasks/estimate. Questa operazione non crea un’attività né riserva crediti. Per OpenAI, effettuare il calcolo in base alle tariffe attuali per milione di token e quindi verificare l’utilizzo effettivo nella risposta o nel record di fatturazione.
