Parametri API GPT Image 2: dimensioni, risoluzione, proporzioni e qualità

L'API GPT Image 2 riceve il nome del modello in model, le dimensioni di uscita in size come pixel WIDTHxHEIGHT e la qualità in quality (low, medium, high o auto). Non esiste un campo resolution né aspect_ratio. Per ottenere un'immagine 16:9 in 4K invii "size": "3840x2160". Le dimensioni devono usare multipli di 16, avere entrambi i lati pari o inferiori a 3840 pixel, restare tra 1:3 e 3:1 e rientrare tra 655.360 e 8.294.400 pixel.

Questa guida copre ogni parametro che cambia l'immagine, con il valore esatto da inviare e l'errore che restituisce un valore sbagliato. Ogni errore qui sotto è stato verificato sull'API in produzione.

Qual è il nome del modello GPT Image 2 nell'API?

Usa gpt-image-2 o gpt-image-2-official. Sono lo stesso modello con gli stessi campi; gpt-image-2 applica un prezzo fisso per immagine consegnata, mentre gpt-image-2-official addebita i token che ogni generazione riporta.

I nomi presi dai titoli non funzionano come ID modello. gpt-image-2.0, GPT Image 2 o chatgpt-images-2 restituiscono tutti HTTP 400 con il codice di errore 20002.

Come si impostano risoluzione e proporzioni?

Con size, in pixel. Scegli le proporzioni e il budget di pixel che vuoi, poi invia la larghezza e l'altezza risultanti:

Sono le stesse conversioni che il Playground usa quando scegli un rapporto e un preset 1K, 2K o 4K. Il 4K quadrato si ferma a 2880x2880 perché un quadrato di 3840 pixel supererebbe il limite di pixel totali.

size: "auto" lascia le dimensioni al modello. È il valore predefinito, ed è comodo, ma imposta dimensioni esplicite quando le immagini devono adattarsi a un layout o essere coerenti tra loro.

OpenAI descrive come sperimentale l'output oltre 2560×1440. Viene accettato entro i limiti indicati qui, ma una tela più grande non garantisce più dettaglio.

Quali valori di size vengono rifiutati?

Fai attenzione alle ultime due righe. Un campo sconosciuto viene rifiutato, ma l'errore non lo nomina. Se ricevi 20001 con il messaggio generico «Check the parameters against the API documentation», cerca un campo che l'API non accetta, come resolution, aspect_ratio o response_format.

Quale qualità scegliere?

quality accetta low, medium, high e auto. I livelli più alti richiedono più tempo e conservano dettagli più fini. xhigh e max appartengono solo a GPT Image 2.5; inviarli a GPT Image 2 restituisce 20001 con un messaggio che nomina quality.

Una routine pratica: fai le bozze in low finché la composizione cambia ancora, controlla texture e testo piccolo in medium e produci le versioni finali in high. Su gpt-image-2 il prezzo è lo stesso a ogni livello. Su gpt-image-2-official i livelli più alti riportano più token in uscita, quindi costano di più. La guida ai prezzi mostra i numeri.

auto lascia scegliere il livello al modello. Imposta un valore esplicito quando confronti esecuzioni diverse, altrimenti due richieste "identiche" potrebbero essere generate a livelli diversi.

Cosa controlla formato e sfondo?

• output_format: png (predefinito) o jpeg. L'output WebP non è disponibile; webp restituisce 20001 con un messaggio che nomina output_format.
• output_compression: da 0 a 100, solo con jpeg.
• background: auto, opaque o transparent. La trasparenza richiede png; transparent con jpeg restituisce 20001 con un messaggio che nomina background.
• n: da 1 a 10 immagini per richiesta. Ti vengono addebitate le immagini consegnate.
• moderation: auto o low.

Come si passano immagini di riferimento e maschere?

Come URL, mai come file o base64. images accetta da 1 a 16 oggetti nella forma {"image_url": "https://..."}, e inviarlo trasforma la richiesta in una modifica. mask accetta un oggetto della stessa forma: un PNG delle dimensioni della prima immagine di riferimento, in cui l'area trasparente indica cosa cambiare. La documentazione elenca i limiti dei file.

Domande frequenti

GPT Image 2 supporta il 4K?

Sì, entro i limiti indicati sopra. 3840x2160 per il 16:9 e 2160x3840 per il 9:16 sono i formati più grandi, e 2880x2880 è il quadrato più grande.

Posso inviare le proporzioni invece dei pixel?

Non all'API. Converti prima il rapporto in dimensioni WIDTHxHEIGHT, usando la tabella qui sopra o il Playground, che mostra le dimensioni esatte prima dell'invio.

Quali sono le dimensioni e la qualità predefinite?

Entrambe sono auto per impostazione predefinita, cioè la scelta spetta al modello. Invia valori espliciti quando ti serve un output prevedibile.

Invia pixel, imposta la qualità, leggi il messaggio di errore

Quasi ogni problema di parametri rientra in tre casi: un rapporto inviato come dimensione, un campo che l'API non accetta o un valore fuori dai limiti. Nel primo e nel terzo caso il messaggio di errore nomina il campo; un messaggio generico che non nomina alcun campo indica il secondo. Tieni questa pagina accanto alla documentazione dell'API GPT Image 2 mentre integri.