> ## Documentation Index > Fetch the complete documentation index at: https://docs.venice.ai/llms.txt > Use this file to discover all available pages before exploring further. # Imágenes con fondo transparente > Genera y edita imágenes PNG o WebP con un canal alfa real usando transparent_background en /image/generate, /image/edit y /image/multi-edit, o background: transparent en el endpoint compatible con OpenAI. La API de imágenes de Venice puede devolver imágenes con un canal alfa real en lugar de un fondo blanco o de cuadros pintado. El modelo compone el sujeto con transparencia desde el principio, de modo que los bordes, las sombras y las regiones semitransparentes (vidrio, cabello, humo) llevan alfa por píxel en lugar de una máscara dura. Esto es distinto de `/image/background-remove`, que toma una imagen opaca ya terminada y segmenta el primer plano a posteriori. Usa la transparencia nativa cuando de todos modos vayas a generar o editar el recurso; usa la eliminación de fondo cuando solo tengas la imagen opaca. Comparación lado a lado: un vaso de té helado renderizado sobre un fondo de estudio opaco frente al mismo vaso sobre un fondo transparente mostrado sobre un patrón de cuadros ## Qué necesitas | Requisito | Detalle | | - | - | | Modelo | Uno marcado con `supportsTransparentBackground: true` en las restricciones de `GET /models`. Actualmente `gpt-image-1-5`, `gpt-image-2-5-flare` y `gpt-image-2-5-sunburst` (más sus variantes `-edit` para los endpoints de edición) | | Formato de salida | `png` o `webp`. JPEG no tiene canal alfa, así que `jpeg` se rechaza | | Parámetro | `transparent_background: true` en `/image/generate`, `/image/edit`, `/image/multi-edit`. `background: "transparent"` en `/images/generations` | Cualquier otra combinación devuelve `400` antes de que se ejecute la inferencia, así que no se te cobra por una solicitud rechazada. ## Paso 1: genera una imagen transparente `/image/generate` es el endpoint nativo. Establece `format` en `png` o `webp` y `transparent_background` en `true`. ```bash theme={"system"} 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 respuesta es `content-type: image/png` con una disposición de píxeles RGBA. Sin `return_binary` obtienes el sobre JSON habitual con una cadena base64 en `images[0]`. `format` tiene como valor predeterminado `webp`, que también admite alfa, así que omitir `format` funciona. Solo falla un `"format": "jpeg"` explícito. Además de activar el flag, indica "no background" o "isolated on transparent background" en el prompt. El flag garantiza un canal alfa; el prompt evita que el modelo dibuje un suelo, una mesa o un telón de fondo que acabaría siendo opaco dentro del cuadro delimitador del sujeto. ## Paso 2: verifica el canal alfa No te fíes de la extensión del archivo. Comprueba el modo de píxel y revisa la distribución del alfa para confirmar que el fondo es realmente transparente y no un relleno blanco aplanado. ```python theme={"system"} 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 resultado correcto tiene una gran proporción de píxeles con alfa `0` (el fondo), una franja de valores parciales a lo largo de los bordes (antialiasing y sombras suaves) y un cuadro delimitador del sujeto más pequeño que el lienzo. Si `im.mode` es `RGB` o la proporción transparente es `0%`, el canal alfa se perdió en algún punto de tu pipeline, normalmente en un paso de redimensionado o recodificación que lo descartó. Tres paneles: la imagen transparente sobre un fondo de cuadros, su canal alfa como máscara en escala de grises y un recorte ampliado del borde de la sombra que muestra un degradado suave Los modelos GPT Image devuelven actualmente la región opaca con alfa `252`–`254` en lugar de `255`. Visualmente es indistinguible, pero si aplicas un umbral `== 255` para encontrar el sujeto, obtendrás una máscara vacía. Usa en su lugar un umbral `> 0` o `>= 250`. ## Paso 3: usa el endpoint compatible con OpenAI Si ya usas el SDK de OpenAI, `/images/generations` acepta el mismo parámetro `background` que usa OpenAI. Establécelo en `"transparent"` y elige `png` o `webp` como `output_format`. ```python theme={"system"} 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` acepta `transparent`, `opaque` o `auto`. `opaque`, `auto` y `null` mantienen el comportamiento predeterminado del modelo, así que el único valor que cambia algo es `transparent`. `output_format` tiene como valor predeterminado `png` en este endpoint, así que puedes omitirlo. ## Paso 4: edita con transparencia Tanto `/image/edit` como `/image/multi-edit` aceptan también `transparent_background`. La imagen fuente no necesita ser transparente; puedes pasar una foto opaca y pedir al modelo que aísle el sujeto mientras la edita. ```bash theme={"system"} 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 "image=@apple.jpg" \ -F "transparent_background=true" \ -o apple-green.png ``` En los endpoints de edición, `output_format` se infiere cuando se omite: normalmente PNG para ediciones 1K y JPEG para 2K/4K, pero cuando `transparent_background` es `true` la inferencia cambia a PNG en todas las resoluciones. Así que solo necesitas enviar `output_format` explícitamente si quieres WebP. La forma de multi-edit es idéntica, con `images[]` en lugar de `image`. Es la opción natural para componer una foto de producto en una nueva escena y recibir el resultado compuesto como un recorte que puedes colocar en tu propio diseño. ## Precios La transparencia no añade ningún recargo. Pagas el precio normal por imagen del modelo, que en GPT Image 2.5 depende de `resolution` y `quality`. Una generación `1K` `low` en `gpt-image-2-5-flare` es la forma más barata de iterar sobre un sticker o un icono antes de pagar por `high` o `4K`. Consulta [Modelos de imagen](/es/models/image) para ver la tabla de precios actualizada. ## Errores La validación se ejecuta antes de llamar al modelo. Ambos mensajes indican cómo solucionarlo. | Solicitud | Estado | Cuerpo | | - | - | - | | `transparent_background: true` con `format` / `output_format` `jpeg` | `400` | `Transparent background requires png or webp output format.` | | `transparent_background: true` en un modelo sin el 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"` en `/images/generations` | `400` | `Transparent background requires png or webp output format.` | `transparent_background: false` con `jpeg` es válido y devuelve un JPEG opaco normal. ## Descubre los modelos compatibles en tiempo de ejecución Los IDs de modelo cambian. En lugar de codificar la lista anterior, filtra `GET /models` por el flag de restricción. La clave solo está presente, como `true`, en los modelos que la admiten. ```bash theme={"system"} curl -s "https://api.venice.ai/api/v1/models?type=image" \ | jq -r '.data[] | select(.model_spec.constraints.supportsTransparentBackground == true) | .id' ``` Usa `type=inpaint` para los endpoints de edición, que devuelven los IDs de modelo `-edit`. ## Cuándo usar esto frente a `/image/background-remove` | | `transparent_background` | `/image/background-remove` | | - | - | - | | Entrada | Un prompt (y opcionalmente una imagen fuente para editar) | Una imagen opaca existente | | Cómo se produce el alfa | El modelo compone con transparencia desde el principio | Un modelo de segmentación enmascara el primer plano a posteriori | | Sombras y reflejos | Se conservan, con alfa parcial, porque el modelo los renderizó como parte del sujeto | Se eliminan junto con el fondo, ya que no forman parte del primer plano | | Elección de modelo | Solo GPT Image 1.5 / 2.5 | Modelo interno fijo, sin campo `model` | | Coste | Precio normal de generación o edición del modelo | Precio fijo de eliminación de fondo | Si de todos modos vas a generar el recurso, solicita la transparencia desde el principio y ahórrate la segunda llamada. Recurre a `/image/background-remove` cuando la imagen opaca ya existe y no quieres regenerarla. El mismo sticker de cohete de dibujos animados compuesto sobre un color sólido oscuro, un degradado cálido y un fondo de cuadros ## Relacionado * [Generación de imágenes](/es/guides/media/image-generation) para tamaños, niveles de calidad y la lista completa de parámetros de `/image/generate` * [Edición de imágenes](/es/guides/media/image-editing) para `/image/edit`, `/image/multi-edit` y `/image/background-remove` * [Modelos de imagen](/es/models/image) para precios y restricciones actuales This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.