/image/background-remove, che prende un’immagine opaca già finita e segmenta il primo piano a posteriori. Usa la trasparenza nativa quando stai comunque generando o modificando l’asset; usa la rimozione dello sfondo quando hai solo l’immagine opaca.
Stesso prompt e stesso seed su gpt-image-2-5-flare. A sinistra: output di default. A destra: transparent_background: true, mostrato sopra una scacchiera. L'ombra proiettata sopravvive come alfa parziale.
Cosa ti serve
Qualsiasi altra combinazione restituisce
400 prima che venga eseguita l’inferenza, quindi non ti viene addebitato nulla per una richiesta rifiutata.
Passo 1: Genera un’immagine trasparente
/image/generate è l’endpoint nativo. Imposta format su png o webp e transparent_background su true.
content-type: image/png con un layout di pixel RGBA. Senza return_binary ottieni il consueto envelope JSON con una stringa base64 in images[0].
Il default di format è webp, che supporta anch’esso l’alfa, quindi omettere format funziona. Fallisce solo un "format": "jpeg" esplicito.
Passo 2: Verifica il canale alfa
Non fidarti dell’estensione del file. Controlla la modalità dei pixel e osserva la distribuzione dell’alfa per confermare che lo sfondo sia davvero trasparente e non un riempimento bianco appiattito.0 (lo sfondo), una fascia di valori parziali lungo i bordi (anti-aliasing e ombre morbide) e un riquadro di delimitazione del soggetto più piccolo del canvas. Se im.mode è RGB o la quota trasparente è 0%, il canale alfa è andato perso da qualche parte nella tua pipeline, di solito in un passaggio di ridimensionamento o ricodifica che lo ha scartato.
Il canale alfa dell'immagine sopra, isolato. L'ombra sotto il bicchiere sfuma attraverso decine di livelli di grigio invece di passare di colpo dal bianco al nero, ed è proprio ciò che serve per comporre l'immagine su sfondi arbitrari.
I modelli GPT Image attualmente restituiscono la regione opaca con alfa
252–254 anziché 255. Visivamente è indistinguibile, ma se applichi una soglia == 255 per trovare il soggetto otterrai una maschera vuota. Usa invece una soglia > 0 o >= 250.Passo 3: Usa l’endpoint compatibile con OpenAI
Se usi già l’SDK di OpenAI,/images/generations accetta lo stesso parametro background usato da OpenAI. Impostalo su "transparent" e scegli png o webp come output_format.
background accetta transparent, opaque o auto. opaque, auto e null mantengono tutti il comportamento di default del modello, quindi l’unico valore che cambia qualcosa è transparent. Su questo endpoint il default di output_format è png, quindi puoi ometterlo.
/images/generations accetta quality, style, output_compression e size per compatibilità con OpenAI, ma li ignora. Sui modelli GPT Image trattati in questa pagina, size non ha effetto: l’output resta all’aspect ratio e alla risoluzione di default del modello. Oltre a model e prompt, i campi che influiscono sull’immagine sono background, output_format e moderation; response_format sceglie solo tra base64 e una data URL. resolution e aspect_ratio non sono campi e lo schema è strict, quindi inviare uno dei due restituisce 400. Ometti quality qui; usa l’endpoint nativo /image/generate quando ti serve controllare il livello (vedi Prezzi più sotto).Passo 4: Modifica con trasparenza
Anche/image/edit e /image/multi-edit accettano transparent_background. L’immagine sorgente non deve essere trasparente: puoi passare una foto opaca e chiedere al modello di isolare il soggetto mentre lo modifica.
output_format viene dedotto quando è omesso: normalmente PNG per gli edit a 1K e JPEG per 2K/4K, ma quando transparent_background è true la deduzione passa a PNG a ogni risoluzione. Quindi devi inviare output_format esplicitamente solo se vuoi WebP.
/image/multi-edit accetta gli stessi campi con due differenze: invia ogni immagine di input come parte images ripetuta e indica il modello con modelId al posto di model. È la scelta naturale per comporre una foto prodotto su una nuova scena e ottenere il risultato composto come ritaglio da posizionare nel tuo layout.
Prezzi
La trasparenza non comporta alcun sovrapprezzo. Paghi il normale prezzo per immagine del modello. Le due route fatturano in modo diverso:
Se devi controllare il costo per immagine, usa l’endpoint nativo. Consulta Modelli di immagini per la tabella prezzi aggiornata.
Errori
La validazione viene eseguita prima che il modello venga chiamato. Entrambi i messaggi indicano come risolvere.transparent_background: false con jpeg va bene e restituisce un normale JPEG opaco.
Scopri i modelli supportati a runtime
Gli ID dei modelli cambiano nel tempo. Invece di inserire nel codice la lista qui sopra, filtraGET /models in base al flag dei constraints. La chiave è presente, con valore true, solo sui modelli che la supportano.
type=inpaint per gli endpoint di edit, che restituiscono gli ID dei modelli -edit.
Quando usare questo rispetto a /image/background-remove
Se stai comunque generando l’asset, richiedi la trasparenza fin da subito e salta la seconda chiamata. Ricorri a
/image/background-remove quando l’immagine opaca esiste già e non vuoi rigenerarla.
Un unico sticker trasparente ottenuto dalla richiesta del Passo 1, posizionato su tre sfondi senza ulteriori elaborazioni.
Correlati
- Generazione di immagini per dimensionamento, livelli di qualità e l’elenco completo dei parametri di
/image/generate - Image Editing per
/image/edit,/image/multi-edite/image/background-remove - Modelli di immagini per prezzi e constraints aggiornati