Immagini con sfondo trasparente

L’API di immagini di Venice può restituire immagini con un vero canale alfa invece di uno sfondo bianco o a scacchiera dipinto. Il modello compone il soggetto con la trasparenza fin dall’inizio, quindi bordi, ombre e regioni semitrasparenti (vetro, capelli, fumo) hanno un valore alfa per pixel anziché una maschera netta. Questo è diverso da /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.

Confronto affiancato: un bicchiere di tè freddo renderizzato su uno sfondo da studio opaco e lo stesso bicchiere su sfondo trasparente mostrato sopra una scacchiera

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

Requisito	Dettaglio
Modello	Uno contrassegnato con `supportsTransparentBackground: true` nei constraints di `GET /models`. Attualmente `gpt-image-1-5`, `gpt-image-2-5-flare` e `gpt-image-2-5-sunburst` (più le rispettive varianti `-edit` per gli endpoint di edit)
Formato di output	`png` o `webp`. JPEG non ha canale alfa, quindi `jpeg` viene rifiutato
Parametro	`transparent_background: true` su `/image/generate`, `/image/edit`, `/image/multi-edit`. `background: "transparent"` su `/images/generations`

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.

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o sticker.png \
  -d '{
    "model": "gpt-image-2-5-flare",
    "prompt": "A die-cut sticker of a cartoon rocket ship, bold outlines, flat colors, no background",
    "format": "png",
    "transparent_background": true,
    "quality": "low",
    "return_binary": true
  }'

La risposta è 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.

Oltre a impostare il flag, scrivi “no background” o “isolated on transparent background” anche nel prompt. Il flag garantisce un canale alfa; il prompt evita che il modello disegni un pavimento, un tavolo o uno sfondo che risulterebbero opachi all’interno del riquadro di delimitazione del soggetto.

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.

from PIL import Image

im = Image.open("sticker.png")
print(im.format, im.mode, im.size)  # PNG RGBA (1024, 1024)

alpha = im.getchannel("A")
hist = alpha.histogram()
total = sum(hist)
print(f"fully transparent: {100 * hist[0] / total:.1f}%")
print(f"partially transparent: {100 * sum(hist[1:255]) / total:.1f}%")
print("subject bbox:", alpha.getbbox())

Un risultato corretto ha un’ampia quota di pixel con alfa 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.

Tre pannelli: l'immagine trasparente sopra una scacchiera, il suo canale alfa come maschera in scala di grigi e un ritaglio ingrandito del bordo dell'ombra che mostra un gradiente morbido

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.

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.venice.ai/api/v1",
    api_key=VENICE_API_KEY,
)

result = client.images.generate(
    model="gpt-image-2-5-flare",
    prompt="A flat vector icon of a paper airplane, isolated, no background",
    output_format="webp",
    background="transparent",
    quality="low",
)

with open("icon.webp", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

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.

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.

curl https://api.venice.ai/api/v1/image/edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "model=gpt-image-2-5-flare-edit" \
  -F "prompt=Make the apple green and remove the background" \
  -F "[email protected]" \
  -F "transparent_background=true" \
  -o apple-green.png

Sugli endpoint di edit, 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. La forma multi-edit è identica, con images[] al posto di image. È 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, che per GPT Image 2.5 dipende da resolution e quality. Una generazione 1K low su gpt-image-2-5-flare è il modo più economico per iterare su uno sticker o un’icona prima di pagare per high o 4K. Consulta Modelli di immagini per la tabella dei prezzi aggiornata.

Errori

La validazione viene eseguita prima che il modello venga chiamato. Entrambi i messaggi indicano come risolvere.

Richiesta	Stato	Body
`transparent_background: true` con `format` / `output_format` `jpeg`	`400`	`Transparent background requires png or webp output format.`
`transparent_background: true` su un modello senza il flag	`400`	`Transparent background is not supported by model 'flux-2-pro'. Use a model with "supportsTransparentBackground": true in its constraints (see GET /api/v1/models).`
`background: "transparent"` con `output_format: "jpeg"` su `/images/generations`	`400`	`Transparent background requires png or webp output format.`

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, filtra GET /models in base al flag dei constraints. La chiave è presente, con valore true, solo sui modelli che la supportano.

curl -s "https://api.venice.ai/api/v1/models?type=image" \
  | jq -r '.data[] | select(.model_spec.constraints.supportsTransparentBackground == true) | .id'

Usa type=inpaint per gli endpoint di edit, che restituiscono gli ID dei modelli -edit.

Quando usare questo rispetto a `/image/background-remove`

	`transparent_background`	`/image/background-remove`
Input	Un prompt (e facoltativamente un’immagine sorgente da modificare)	Un’immagine opaca esistente
Come viene prodotto l’alfa	Il modello compone con la trasparenza fin dall’inizio	Un modello di segmentazione maschera il primo piano a posteriori
Ombre e riflessi	Mantenuti, con alfa parziale, perché il modello li ha renderizzati come parte del soggetto	Rimossi insieme allo sfondo, poiché non fanno parte del primo piano
Scelta del modello	Solo GPT Image 1.5 / 2.5	Modello interno fisso, nessun campo `model`
Costo	Normale prezzo di generazione o edit del modello	Prezzo fisso di 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.

Lo stesso sticker del razzo cartoon composto su un colore pieno scuro, un gradiente caldo e una scacchiera

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-edit e /image/background-remove
Modelli di immagini per prezzi e constraints aggiornati

Documentazione

Per iniziare

Testo e chat

Immagini

Video

Audio

Ricerca e RAG

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

Immagini con sfondo trasparente

Cosa ti serve

Passo 1: Genera un’immagine trasparente

Passo 2: Verifica il canale alfa

Passo 3: Usa l’endpoint compatibile con OpenAI

Passo 4: Modifica con trasparenza

Prezzi

Errori

Scopri i modelli supportati a runtime

Quando usare questo rispetto a `/image/background-remove`

Correlati

​Cosa ti serve

​Passo 1: Genera un’immagine trasparente

​Passo 2: Verifica il canale alfa

​Passo 3: Usa l’endpoint compatibile con OpenAI

​Passo 4: Modifica con trasparenza

​Prezzi

​Errori

​Scopri i modelli supportati a runtime

​Quando usare questo rispetto a /image/background-remove

​Correlati

Cosa ti serve

Passo 1: Genera un’immagine trasparente

Passo 2: Verifica il canale alfa

Passo 3: Usa l’endpoint compatibile con OpenAI

Passo 4: Modifica con trasparenza

Prezzi

Errori

Scopri i modelli supportati a runtime

Quando usare questo rispetto a `/image/background-remove`

Correlati