GPT Image 2 / 2.5: generazione e modifica delle immagini

Scegli l'endpoint prima di scrivere la richiesta: text-to-image usa /images/generations; image-to-image usa /images/edits con file immagine caricati. Menzionare “immagine di riferimento 1” in un prompt non allega alcuna immagine.

Modelli ed endpoint

ID modello	Text-to-image	Image-to-image
gpt-image-2	/images/generations	/images/edits + file immagine
gpt-image-2.5-sunburst	/images/generations	/images/edits + file immagine
gpt-image-2.5-flare	/images/generations	/images/edits + file immagine

Questi sono ID modello distinti. Cambia model in modo esplicito quando passi da un modello all'altro; GPT Image 2.5 non è un alias di GPT Image 2. Verifica la disponibilità attuale e i prezzi dell'account nel marketplace.

Operazione	Metodo ed endpoint	Formato richiesta
Text-to-image	POST https://apimaster.ai/v1/images/generations	JSON
Image-to-image / modifica	POST https://apimaster.ai/v1/images/edits	multipart/form-data con file immagine reali
Modifica immagine asincrona	POST https://apimaster.ai/v1/images/edits/async	Stessi file multipart delle modifiche; restituisce un task ID
Text-to-image asincrono	POST https://apimaster.ai/v1/images/generations/async	JSON; restituisce un task ID
Interrogazione di un task	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Autenticazione Bearer

Per una risposta di task dalla modifica delle immagini, usa /images/edits/async. Carica gli stessi file e campi delle modifiche sincrone, poi interroga /tasks/{task_id}. Non spostare una richiesta di modifica su generations/async. Questi endpoint di task riutilizzano il contratto asincrono esistente: un upstream asincrono può restituire il proprio task tempestivamente, mentre un upstream sincrono può completare la modifica prima che il gateway restituisca un task ID. Non sono una garanzia di esecuzione immediata in background. Non usare Chat Completions per questi modelli.

Autenticazione e timeout

Crea una chiave API e invia Authorization: Bearer YOUR_API_KEY. Le richieste di generazione JSON usano Content-Type: application/json. Per il caricamento dei file, lascia che cURL o la tua libreria HTTP generi il boundary multipart; non impostare manualmente l'header Content-Type.

Consenti almeno 180 secondi per le richieste di base, 300 secondi per risoluzioni più alte e 600 secondi per modifiche impegnative o alta qualità. Un timeout del client non dimostra che la richiesta upstream si sia interrotta. Evita invii duplicati immediati.

Text-to-image: generazione JSON

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Per Sunburst o Flare, sostituisci l'ID del modello con gpt-image-2.5-sunburst o gpt-image-2.5-flare. Non aggiungere immagini di riferimento a questo esempio; usa gli esempi di modifica riportati sotto.

Image-to-image: caricamento di un singolo riferimento

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Sostituisci reference.png con un'immagine locale esistente. @ indica a cURL di caricare i byte del file; image=reference.png invia solo una stringa con il nome del file. Questo pattern di endpoint si applica anche a gpt-image-2 e gpt-image-2.5-sunburst.

Image-to-image: caricamento di più riferimenti

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Ripeti lo stesso campo image[] per ogni file, nell'ordine descritto nel prompt. n è il numero di immagini in output, non il numero di riferimenti. I limiti sui riferimenti dipendono dal modello selezionato e dalla route disponibile; non dare per scontato un limite universale di 16 immagini. Parti con un riferimento e n=1, poi aggiungi input secondo necessità.

Esempio di modifica in Python

Installa requests. Questo esempio carica un file reale e gestisce sia risposte immagine URL sia base64.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

Per più file, passa una lista di voci ("image[]", (filename, file_object, mime_type)) ripetute a files. Mantieni ogni file aperto fino al completamento della richiesta.

Modifica immagine asincrona

Usa questo endpoint con GPT Image 2, Sunburst o Flare quando la tua applicazione consuma task ID. Le regole di caricamento dei file, l'ordine dei riferimenti, i limiti di capacità e l'autenticazione sono gli stessi delle modifiche sincrone.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

L'invio restituisce data[0].task_id. Interroga usando lo stesso ID modello:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

Un task tracciato completato ha questa forma; ogni immagine generata è inclusa:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

Il task appartiene all'account che l'ha inviato. Interrogalo con una chiave API valida per quell'account. Un invio fallito restituisce un errore anziché un task utilizzabile; una volta restituito un task ID, continua a interrogare quel task invece di inviare di nuovo la modifica. Consulta la tabella degli stati di polling qui sotto.

Integrazioni esistenti con URL o base64

Se il tuo input è un URL, scarica l'immagine nella tua applicazione e carica i suoi byte su /images/edits. Se è un data URI base64, decodifica il payload in un file o in un buffer di byte e caricarlo. Non inviare l'URL o il testo base64 come se fosse un caricamento di file.

Alcune route di GPT Image 2 supportano l'estensione image_urls su generations. Non si tratta di un contratto portabile di modifica delle immagini e non deve essere assunto come funzionante con GPT Image 2.5. Le nuove integrazioni dovrebbero usare gli esempi di modifiche multipart sopra. Una richiesta JSON contenente image_urls, image o images non equivale al caricamento di file su edits.

Parametri e limiti di capacità

Campo	Uso
model	Obbligatorio; usa un ID modello esatto della tabella sopra
prompt	Obbligatorio; descrivi il risultato e l'ordine dei riferimenti
image / image[]	File effettivamente caricati per le modifiche; usa PNG o JPEG per gli esempi di base
n	Numero di immagini in output; parti con 1; il massimo dipende dalla route
size	Opzionale; 1024x1024 è l'esempio di base; altre dimensioni in pixel o proporzioni dipendono dalla route
resolution	Estensione opzionale specifica della route come 1k, 2k, 4k; non ogni model/route supporta ogni tier
quality	Opzionale; i valori accettati e il costo dipendono dalla route
background, output_format, output_compression	Opzionali; trasparenza e codifica dell'output richiedono il supporto della route
mask	Solo GPT Image 2, quando una route di edits disponibile supporta mask caricati; non supportato dall'attuale gestore multipart di GPT Image 2.5

Per GPT Image 2, il supporto delle mask deve essere verificato separatamente dalla modifica ordinaria con riferimenti. Una mask PNG compatibile deve corrispondere alle dimensioni dell'input e includere un canale alpha. L'attuale endpoint multipart di GPT Image 2.5 rifiuta i file mask caricati; non aggiungere una mask agli esempi Sunburst o Flare sopra. Non dare per scontato che una soluzione alternativa JSON con mask_url sia supportata senza aver verificato la route scelta.

Invia solo i campi opzionali di cui hai bisogno. Possono modificare le route idonee e il prezzo; impostare esplicitamente un valore predefinito non è sempre equivalente a ometterlo. Nessuna tabella di dimensioni in pixel fissa o elenco di parametri avanzati si applica uniformemente ai tre ID modello. Prezzi effettivi e capacità supportate seguono il marketplace e la risposta della richiesta.

Risposte sincrone

Una generazione o modifica riuscita restituisce le voci immagine in data:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

A seconda della route e del formato di output, una voce può invece contenere b64_json. Decodificalo in byte dell'immagine. Scarica tempestivamente gli URL dei risultati temporanei. Una risposta HTTP 200 o il solo conteggio delle immagini non dimostrano che i dettagli dei riferimenti siano stati preservati; confronta il risultato con l'input.

Task asincroni: invio e polling

Per text-to-image, invia JSON senza immagini di riferimento a generations/async. Per la modifica delle immagini, usa l'esempio multipart edits/async sopra. Entrambi usano lo stesso endpoint di interrogazione dei task:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

L'invio di solito riporta submitted; un upstream può già riportare uno stato di completamento. Il primo polling può risultare già completo. Un task ID non garantisce una risposta immediata: se l'upstream selezionato è sincrono, la piattaforma attende il completamento della generazione prima di restituire il task. Mantieni un timeout di invio adeguato.

Interroga con lo stesso ID modello usato per l'invio:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Stato del task	Azione
pending, submitted, processing, in_progress	Attendi; interroga di nuovo dopo 3–5 secondi
succeeded, success, completed	Leggi ogni voce in data.result.images; i task tracciati usano una url stringa, mentre le risposte upstream legacy possono usare un array di URL
failed, error, cancelled	Interrompi il polling ed esamina l'errore

Usa una scadenza complessiva di polling finita, ad esempio 10 minuti. Se scade, conserva il task ID per verifiche successive invece di creare automaticamente un altro task a pagamento. Le risposte di interrogazione dei task e le risposte immagine sincrone hanno strutture diverse.

Risoluzione dei problemi con le immagini di riferimento

1. Verifica che il percorso effettivo della richiesta sia /v1/images/edits o /v1/images/edits/async, non generations o generations/async.
2. Verifica che il multipart contenga i byte del file sotto image o image[] ripetuti, con un boundary generato. Il testo del prompt, i nomi dei file e i conteggi dei riferimenti non sostituiscono i file.
3. Controlla l'ID modello esatto. Un'estensione di GPT Image 2 non è automaticamente supportata da Sunburst o Flare.
4. Se i dettagli del task/log non mostrano un'anteprima, non concludere che nessuna immagine sia stata inviata: i log possono omettere i dati base64 e i contenuti dei file caricati. Al contrario, un conteggio dei riferimenti registrato non dimostra che un upstream abbia usato le immagini.
5. Prova con un riferimento semplice contenente scritte o forme distintive e chiedi una modifica dello sfondo senza descrivere quei dettagli. Confronta visivamente l'output.
6. Per l'assistenza, conserva l'ID della richiesta (X-Oneapi-Request-Id), il task ID se presente, il modello, l'endpoint, il timestamp, i campi della richiesta sanitizzati e le immagini di riferimento. Non condividere mai la tua chiave API.

Per una risposta 400, esamina la compatibilità di endpoint e parametri; 401 indica un fallimento dell'autenticazione; 429 indica un limite di frequenza/quota. Per timeout o fallimenti upstream, conserva l'ID richiesta/task e controlla il task esistente o il registro di utilizzo prima di inviare di nuovo.