API para eliminar fondos: entregue PNG de producto transparentes

Tiene unos cientos de fotos de producto sobre mesas grises y alféizares, y la tienda, el marketplace o el diseñador necesita cada una como PNG transparente. SpicyAPI Background Remover lo hace en una sola llamada: usted envía la URL de una foto y recibe el sujeto principal en un PNG transparente con el ancho y el alto originales. El trabajo que queda es suyo: confirmar que el archivo realmente tiene alfa, revisar los bordes sobre los fondos donde se usará y exportar las copias planas que pida cada destino.

Pruébelo primero en el Playground

Abra el Playground de background-remover-v1. Suelte una foto de producto en Input image, compruebe el precio y pulse Run model. Inspeccione el resultado transparente sobre fondos claros y oscuros antes de usar la misma foto en código.

Qué recibe y qué devuelve el endpoint

La salida conserva las dimensiones del lienzo de origen, así que puede colocar el recorte sobre un fondo nuevo sin reescalar. Use el canal alfa devuelto como límite del recorte; conservar el mismo lienzo no garantiza que cada borde o color del primer plano permanezca intacto. Los detalles están en la página del modelo Background Remover.

Vea primero un resultado real

El ejemplo de la propia página del modelo es un frasco cuentagotas esmerilado sobre un fondo gris de estudio, de 1024 × 1536 píxeles. Son los archivos de antes y después de esa página; el «después» se muestra aquí sobre el fondo de la página.

Al ejecutar el script de comprobación de las secciones siguientes con este par, se obtienen las cifras de un buen resultado: la salida tiene canal alfa, el tamaño coincide con el original, alrededor del 78 % de los píxeles están totalmente transparentes, alrededor del 22 % son sólidos y solo alrededor del 0.35 % son píxeles de borde semitransparentes. La caja del sujeto mide 335 × 1 234 píxeles. Compuesto sobre un fondo azul marino oscuro, la punta del cuentagotas, el collar cepillado y los hombros de vidrio esmerilado no muestran ningún halo claro.

Haga la llamada

Instale spicyapi y pillow con python -m pip install spicyapi pillow. Defina SPICY_API_KEY y IMAGE_URL con la URL directa de su imagen de origen y ejecute este ejemplo. Le pide confirmar el precio, crea la tarea, espera a que termine, guarda el recorte y escribe vistas previas sobre fondo claro y oscuro.

import os
import urllib.request
import uuid
from io import BytesIO
from pathlib import Path

from PIL import Image
from spicyapi import SpicyClient, output_assets

client = SpicyClient()
model = "spicyapi/background-remover-v1/edit"
inputs = {"image_url": os.environ.get("IMAGE_URL", "https://cdn.spicyapi.ai/models/examples/inputs/e82b71db9e3d0e5f.png")}

quote = client.quote_task(model=model, input_data=inputs)
if input(f"Maximum ${quote['maxCharge']}. Create? [y/N] ") != "y":
    raise SystemExit("Stopped without creating a task.")

task = client.create_task(model=model, input_data=inputs, idempotency_key=str(uuid.uuid4()),
                          quote_id=quote["quoteId"], expected_cost=quote["estimatedCost"])
print("Task:", task["taskId"])  # keep this ID: a timeout does not cancel the task
task = client.wait_for_terminal(task["taskId"])
if task["state"] != "succeeded":
    raise RuntimeError(str(task.get("errorMessage", task["state"])))

asset = output_assets(task)[0]
request = urllib.request.Request(asset["url"], headers={"User-Agent": "SpicyAPI-Blog-Example/1.0"})
with urllib.request.urlopen(request, timeout=120) as response:
    data = response.read()
Path("cutout.png").write_bytes(data)

with Image.open(BytesIO(data)) as image:
    if image.format != "PNG":
        raise RuntimeError("Expected a PNG cutout.")
    rgba = image.convert("RGBA")
alpha = rgba.getchannel("A")
values = list(alpha.getdata())
print({"size": rgba.size, "alpha_min_max": alpha.getextrema(),
       "clear_fraction": sum(v <= 8 for v in values) / len(values),
       "solid_fraction": sum(v >= 247 for v in values) / len(values),
       "soft_fraction": sum(8 < v < 247 for v in values) / len(values),
       "subject_box": alpha.getbbox()})
for name, colour in [("light", "#f5f2e8"), ("dark", "#162235")]:
    Image.alpha_composite(Image.new("RGBA", rgba.size, colour), rgba).convert("RGB").save(name + ".jpg")

Para reintentar la misma solicitud tras perder la respuesta, reutilice su clave de idempotencia en lugar de crear una nueva (referencia de idempotencia). Para subir archivos locales, consulte el SDK de Python y la documentación de medios.

Verifique la transparencia decodificando el archivo

Una vista previa blanca no prueba nada. Puede ser un recorte genuino sobre una página blanca, una imagen opaca con fondo blanco o un damero pintado en los píxeles. Decodifique el archivo y lea su canal alfa. La especificación PNG define cómo se almacena el alfa; en la práctica necesita saber si algunos píxeles pueden ser transparentes tras decodificar, no lo que diga el nombre del archivo.

El ejemplo informa de cómo se distribuye el alfa y escribe composiciones sobre crema y azul marino oscuro para revisarlas con Pillow. Compare las dimensiones que informa con las de su original.

Fíjese en los umbrales. Contar solo el alfa 255 como opaco induce a error: en la salida del frasco cuentagotas, alrededor del 14 % de los píxeles tiene un alfa de 1 a 254, pero casi todos son 254, que visualmente es sólido. Si trata el alfa hasta 8 como transparente y desde 247 como sólido, la fracción suave queda para lo que realmente le importa: bordes suavizados, cabello y material genuinamente translúcido.

Cómo leer el informe:

• Que falte el canal alfa, o que alpha_min_max sea (255, 255), significa que no hay transparencia: investigue el flujo antes de revisar bordes.
• Un clear_fraction cercano a 0 en una foto que tenía fondo, o un solid_fraction cercano a 0, significa que se perdió el sujeto o que el resultado es una neblina.
• Una diferencia de tamaño suele indicar un original girado por EXIF o un cambio de tamaño en su propio código, ya que el endpoint conserva las dimensiones.
• Un soft_fraction alto es normal en vidrio, tela y cabello, y una señal de alerta en una taza mate. Defina los umbrales por categoría de producto después de ver un conjunto piloto, no un único número global.
• Una caja del sujeto que toca el borde del lienzo en una foto que recortó con holgura sugiere que se conservó un segundo objeto.

Prepare la foto sin cambiar el producto

Decida qué cuenta como producto antes de fotografiar o recortar: un lazo, el envase y una sombra de contacto están dentro o fuera, y la herramienta no puede adivinar un encargo que nunca se escribió. No repinte un borde astillado ni invente un logotipo ausente; un defecto que el anuncio debe mostrar se queda en la foto.

• Recorte para quitar objetos que compiten, pero deje margen alrededor de cada extremo, para que un asa o una correa no queden cortadas antes de que la API las vea.
• Los objetos superpuestos no se arreglan recortando, porque hay que adivinar el límite oculto. Vuelva a fotografiar y envíe las superposiciones, los soportes de exposición transparentes y los sujetos cortados a un carril de excepciones, para que no atasquen el lote normal.
• Envíe el archivo más limpio. Las reexportaciones repetidas a JPEG dejan artefactos de bloque justo donde el borde necesita detalle; conserve una copia de trabajo sin pérdida. Convierta los perfiles de color de forma deliberada, porque una conversión descuidada cambia el color del producto antes de que nadie revise el recorte.

Revise el borde donde se usará la imagen

Ponga el recorte sobre el fondo de destino real, no solo sobre la página en la que lo revisa. Un recorte que se ve limpio sobre crema puede mostrar un borde pálido sobre azul marino oscuro; ese borde es color del fondo original que quedó en píxeles parcialmente transparentes. Compruebe a tamaño de entrega, para ver si un defecto importa, y al 100 %, para ver su forma. Las dos composiciones del script usan crema y azul marino oscuro; sustitúyalas por los colores de su marca.

Mire las zonas por las que se reconoce este tipo de producto, no cada píxel por igual: el interior del asa de una taza, el borde y el pie, los cordones y las suelas, las cerdas, la punta del cuentagotas. Compare original, alfa y composición con la misma escala y el mismo encuadre. Cuando rechace un archivo, nombre la característica perdida y el destino («abertura del asa rellena en la composición oscura»), para que la siguiente persona sepa si debe recortar, retocar o volver a fotografiar.

Tres situaciones requieren una decisión, no un reintento:

• Huecos dentro de la silueta. La abertura de un asa o el espacio entre los travesaños de una silla pertenecen al fondo. Una comprobación solo del contorno puede parecer correcta aunque el hueco esté relleno. Compruébelo sobre la composición oscura.
• Sombras. Una sombra de contacto asienta un producto; una sombra proyectada larga arrastra la textura del fondo al recorte. Decida si el máster conserva una y si el diseño dibujará la suya. Si añade la suya, suavice o elimine la sombra que ya trae el original para que no choquen dos.
• Vidrio y material translúcido. El color de una botella incluye la luz del fondo que la atraviesa, así que ningún recorte puede dar una botella físicamente correcta sobre cualquier fondo nuevo; un reflejo pálido de estudio que se ve natural sobre blanco puede verse mal sobre oscuro. Conserve el alfa parcial en plástico y tela translúcidos en lugar de umbralizarlo a 0 o 255, y no erosione toda la máscara para quitar un halo: adelgazaría el producto y perdería detalles finos. Retoque localmente sobre una copia.

Corrija el fallo en la etapa que lo causó

Clasifíquelo antes de volver a ejecutar. Repetir la llamada cuesta dinero y, en la mayoría de estos casos, no cambia nada.

No hay prompt con el que empujar la herramienta, así que las palancas son la fotografía de entrada y lo que haga después de la llamada. Si una categoría falla una y otra vez, cambie cómo se fotografía en lugar de repetir solicitudes.

Aplane para destinos que exigen fondo sólido

Los marketplaces suelen pedir un JPEG sobre blanco. JPEG no tiene alfa, así que exportar el máster a JPEG rellena la zona transparente con un color por defecto que nadie aprobó. Aplane sobre un color elegido, conserve el PNG como máster y cambie el tamaño de forma uniforme (nunca estire el ancho y el alto por separado). El light.jpg que escribe el script es exactamente este paso sobre crema; para blanco, cambie el color en el bucle o exporte un JPEG aplanado aparte desde su editor de imágenes. Compruebe el archivo plano, no solo el máster: el remuestreo, la conversión de color y la compresión añaden sus propios defectos. Si un halo aparece solo después de subir a su tienda o CMS, compare los píxeles decodificados del máster, de su exportación y de la miniatura de la plataforma; a menudo la causa es el cambio de tamaño o la recompresión de la plataforma, no el recorte.

Cuándo otra ruta es la herramienta adecuada

Para un recorte simple, Background Remover es la ruta de menor precio de esta tabla y conserva el tamaño del lienzo de origen. Use otra ruta cuando necesite algo que deliberadamente no ofrece.

Si un modelo generativo devuelve un PNG, eso no lo hace transparente: un PNG puede llevar un fondo blanco opaco. Decodifique cada resultado con el mismo script. Cuando importan los píxeles exactos del producto (etiquetas, logotipos, texto del envase), prefiera la ruta de extracción a un redibujado generativo.

Procese un lote sin ahogar a los revisores

La llamada al modelo es barata y rápida; la revisión es el cuello de botella. Empiece con un piloto de una docena de fotos con derechos liberados que representen el catálogo: un objeto sólido limpio, uno con asa o abertura, uno brillante, uno con borde fino, uno con un objeto que compite. El piloto decide qué categorías pasan por una revisión ligera y cuáles siempre van a una persona.

• Envíe con concurrencia acotada y mantenga una cola de descargas aparte, para que una descarga lenta nunca desencadene una extracción repetida. Reintente una descarga fallida contra el resultado existente mientras su enlace sea válido. La guía de contrapresión cubre el diseño de la cola.
• Guarde por revisión de origen su propio ID de recurso, la suma de comprobación del original, el ID de tarea, la ubicación de la salida y la decisión de revisión. Un SKU solo no basta: un producto tiene varios ángulos y repeticiones de sesión.
• Trate «succeeded» como «listo para inspección», nunca como «publicar». Ejecute el script automáticamente y envíe a una persona solo los archivos señalados y una muestra. Las categorías que superan el piloto (objetos sólidos sobre fondos neutros) pueden pasar a un carril más ligero con muestreos periódicos para detectar la deriva; los artículos reflectantes, transparentes y ambiguos siguen con revisión completa. Revise las imágenes principales de campaña antes que los ángulos secundarios, en lugar de seguir el orden de finalización.
• Para recibir avisos de finalización, consulte la guía de polling frente a Webhook para tareas asíncronas; en ambos casos el resultado alimenta el mismo paso de inspección.
• Haga una pausa cuando los fallos compartan una causa. Diez aberturas de asa perdidas son información sobre el conjunto de origen, no diez motivos para reintentar.

Cuánto cuesta por imagen aceptada

Cien recortes cuestan $0.48 y mil cuestan $4.80. La cifra que importa es el gasto por máster aceptado. Como ejemplo de planificación, un lote de 100 primeros recortes más 10 recortados de nuevo son 110 × $0.0048 = $0.528; si 95 superan la revisión, son unos $0.0056 por imagen aceptada.

El tiempo de revisión suele costar más que la API. Las palancas útiles están aguas arriba: si la mayor parte del tiempo de revisión se va en botellas de vidrio, una iluminación mejor para ellas ahorra más que cualquier diferencia de precio. Un recorte completado que usted rechaza sigue siendo una salida completada y cobrada; las tareas fallidas y caducadas liberan su retención.

Mantenga separados el original, el máster y las exportaciones

Conserve la foto original, el máster PNG transparente y cada copia de entrega aplanada como archivos distintos, nombrados según lo que son (por ejemplo <asset>-source, <asset>-cutout-master, <asset>-catalogue-cream), y mantenga las versiones retocadas aparte de la salida de la API sin tocar, para que un halo posterior pueda atribuirse al recorte o a la exportación. Guarde con cada máster el tamaño de destino aprobado, para que una aprobación a tamaño de tarjeta no se confunda con una a tamaño de imagen principal.

Registre cada rechazo bajo una sola categoría: sujeto equivocado, característica perdida, halo, fragmento de fondo sobrante o defecto de exportación. Un recuento solo importa cuando cambia algo: una regla de recorte, un carril manual para el vidrio, un preajuste de exportación corregido. Dé al fotógrafo reglas de captura concretas («mantener visible todo el asa; sin caja de regalo detrás de la abertura», «fondo más oscuro para productos pálidos») en lugar de «hazlo más fácil para la IA».

Preguntas

¿Existe una API gratuita para eliminar fondos?

No para este endpoint: cada salida completada cuesta $0.0048, así que un piloto de 100 fotos cuesta $0.48. Si el requisito es que sea gratis, alojar usted mismo un eliminador de código abierto como rembg evita las tarifas por imagen, pero entonces lo opera y lo ajusta usted; la ruta alojada ofrece un endpoint estable y un coste predecible.

¿Guardar el resultado como PNG hace transparente el fondo?

No. Un PNG puede llevar alfa, pero también puede contener un fondo blanco opaco. Decodifique el archivo y lea el canal alfa, y luego revise composiciones sobre fondo claro y oscuro. Cambiar la extensión de un JPEG a .png no añade nada.

¿Puedo indicarle que conserve el asa, el cabello o la sombra?

No en esta tarea: su entrada es solo la URL de la imagen. Recorte el original, vuelva a fotografiar o retoque localmente. Si quiere un resultado guiado por prompt, use una ruta de edición de imagen de la tabla anterior y verifique después el producto y el alfa.

¿Cómo debo empezar?

Elija un producto representativo y un destino. Envíe la foto, decodifique el PNG, revise los bordes sobre dos fondos, aplane la derivada aprobada y pida al diseñador que la abra en el diseño real. Después ejecute los miembros más difíciles de su conjunto piloto y anote cuáles necesitan una nueva sesión o un carril manual antes de programar todo el catálogo.

Deje que un Agent se encargue de la llamada

Use un Agent cuando quiera que prepare las entradas y devuelva el resultado mientras usted aprueba el precio y las decisiones creativas.

• CLI: con el mismo objeto de entrada guardado como input.json, use npx @spicyapi/cli tasks create --model spicyapi/background-remover-v1/edit --input-file input.json --wait. La CLI le pide confirmar el precio; conserve el ID de tarea devuelto para la recuperación.
• MCP: pida a su asistente que use spicyapi_task_create para spicyapi/background-remover-v1/edit y luego spicyapi_task_wait. El servidor MCP solicita confirmación del precio antes de crear la tarea.
• Skill: instálelo con npx skills add spicyapi-ai/spicy-skill y pida después a $spicyapi que ejecute el mismo flujo y se detenga para su aprobación. El Skill usa una conexión CLI o MCP ya configurada.