Guía de migración de la API de remove.bg

1

Lee esto primero

Las cuatro cosas que no son iguales.

size tiene preview como valor por defecto, igual que en remove.bg, pero aquí preview es una imagen gratuita con marca de agua de hasta 640 px (remove.bg: 0,25 megapíxeles sin marca de agua). Una integración que nunca defina size recibirá vistas previas con marca de agua; pasa size=auto o un nivel de pago para obtener el resultado sin marca de agua.
No afirmamos que haya compatibilidad a nivel de SDK. Tres clientes de terceros —el paquete removebg de PyPI, el paquete oficial remove.bg de npm y removebg-cli— pasaron nuestras pruebas el 22 de septiembre de 2026, pero no hacemos pruebas de regresión con ellos versión a versión; los clientes HTTP escritos a mano son la vía que damos por soportada.
shadow_type, shadow_opacity, add_shadow y semitransparency se aceptan y se validan pero nunca cambian el resultado, igual que en remove.bg para sujetos que no son coches; no hay ningún modelo específico para coches.
Cada llamada cuenta como una imagen dentro del límite de tu clave, de 40 imágenes por minuto (remove.bg permite 500). Gestiona el 429 con Retry-After o escríbenos para ampliar el límite.

2

Antes y después

La misma solicitud contra cada servicio.

remove.bg

1curl -X POST "https://api.remove.bg/v1.0/removebg" \2  -H "X-Api-Key: REMOVEBG_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png

PixMiller

1curl -X POST "https://api.pixmiller.com/v1.0/removebg" \2  -H "X-Api-Key: PIXMILLER_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png6# 200 OK → image bytes, written straight to out.png7# X-Credits-Charged: 1   X-Width: 1200   X-Height: 1600   X-Type: product

3

Parámetros admitidos

Parámetro	Estado	Notas
`image_file`	Igual	Subida multipart. JPG / PNG / WebP, hasta 20 MB (remove.bg: 22 MB).
`image_url`	Igual	URL pública de la imagen, que descargamos por nuestra parte con el mismo límite de 20 MB.
`image_file_b64`	Igual	Imagen codificada en Base64 en el cuerpo de la solicitud, igual que en remove.bg.
`size`	Difiere	Los mismos valores, el mismo valor por defecto (preview) y los mismos topes de megapíxeles, pero aquí preview es una imagen gratuita con marca de agua de hasta 640 px, no 0,25 MP sin marca de agua. medium / hd / 4k / full / 50MP cuestan 1 crédito cada uno; auto usa el nivel de pago mientras queden créditos.
`format`	Igual	auto / png / jpg / webp / zip: el zip contiene color.jpg y alpha.png igual que en remove.bg. Accept: application/json devuelve el sobre base64. La salida PNG está limitada a 10 megapíxeles.
`type, type_level`	Difiere	Aceptado; type se asigna a nuestros propios modelos. X-Type informa de una clase genérica —person, product, animal, car u other— y type_level=2 / latest devuelven las mismas clases genéricas.
`crop, crop_margin`	Igual	Recorta al sujeto con la misma sintaxis de margen y el mismo tope de 50% / 500 px.
`roi`	Igual	Región de interés en píxeles o porcentaje, igual que en remove.bg.
`scale, position`	Igual	Escala del sujeto (10%–100% u original) y posición, igual que en remove.bg.
`channels`	Igual	rgba (por defecto) o alpha solo para la máscara.
`bg_color`	Igual	Transparente por defecto; hexadecimal de 3 / 4 / 6 / 8 dígitos con o sin #, o un nombre de color.
`bg_image_file, bg_image_url`	Igual	Escalada para cubrir la salida y centrada; no se puede combinar con bg_color.
`add_shadow, shadow_type, shadow_opacity`	Sin efecto	Se valida con los valores de remove.bg, pero nunca se genera ninguna sombra.
`semitransparency`	Sin efecto	Aceptado; las zonas semitransparentes siempre se tratan automáticamente.

Cada parámetro se valida con los propios rangos de valores de remove.bg, de modo que un valor inválido devuelve un 400 invalid_parameter en lugar de ignorarse en silencio, exactamente como responde remove.bg.

4

Qué se comporta de otra forma

Código de estado 200 OK con los bytes de la imagen, igual que remove.bg: el código que comprueba == 200 sigue funcionando. (El endpoint propio /api/v1/remove de PixMiller responde 201 con JSON; esta vía de compatibilidad, deliberadamente, no lo hace.)

Cuerpo de la respuesta Los bytes de la imagen, exactamente igual que remove.bg. Envía Accept: application/json para obtener en su lugar el sobre base64 de remove.bg, o format=zip para color.jpg más alpha.png.

Response headers Se devuelven X-Credits-Charged, X-Width, X-Height, X-Type, X-Foreground-Top / -Left / -Width / -Height y X-RateLimit-Limit / -Remaining / -Reset. X-Type es una clase genérica (person / product / animal / car / other) en lugar del vocabulario más fino de remove.bg.

Errores Los errores usan la forma JSON:API de remove.bg: {"errors":[{"title":"…","code":"…"}]} — un array, así que errors[0].title se lee igual que antes. Una clave ausente es 403 auth_failed y una incorrecta 403 invalid_api_key, un saldo vacío es 402 y la limitación es 429.

Créditos preview es gratis; cada nivel de pago cuesta 1 crédito por imagen, que se cobra solo después de haber recuperado el resultado, de modo que una llamada fallida nunca cuesta un crédito. No hay cuota mensual gratuita.

Límite de velocidad 40 imágenes por minuto y clave (remove.bg: 500). Cada llamada cuenta como una imagen, y X-RateLimit-Limit / -Remaining / -Reset reflejan ese cupo por imagen; gestiona el 429 con Retry-After.

5

Consultar tu saldo

El endpoint de cuenta informa del saldo de créditos restante de la clave en data.attributes.credits, de modo que una comprobación de saldo escrita para remove.bg conserva su forma. No hay cuota mensual gratuita, así que free_calls siempre es 0.

GET /v1.0/account

1curl "https://api.pixmiller.com/v1.0/account" \2  -H "X-Api-Key: PIXMILLER_KEY"

6

Errores

400 invalid_parameter Un valor fuera del rango de remove.bg para size / format / crop / scale / … o falta la fuente de la imagen; el title indica el parámetro.

400 file_too_large La imagen de entrada supera los 20 MB.

400 unknown_foreground No se ha podido encontrar ningún primer plano en la imagen.

402 insufficient_credits Se solicitó un nivel de pago pero el saldo está vacío. No se cobra nada.

403 auth_failed / invalid_api_key Falta el encabezado X-Api-Key (auth_failed) o es incorrecto (invalid_api_key): 403 igual que en remove.bg, no 401.

429 rate_limit_exceeded Límite de velocidad superado. Reintenta después del encabezado Retry-After.

502 result_fetch_failed No se ha podido recuperar el resultado del almacenamiento. No se ha cobrado nada: vuelve a intentar la solicitud.

El código de estado transmite el significado y code usa el propio vocabulario de remove.bg: un switch sobre errors[0].code sigue funcionando.

Alternativa a remove.bg Contáctanos