Guia de migração da API do remove.bg

1

Leia isto primeiro

As quatro coisas que não são iguais.

size tem preview como padrão, como no remove.bg — mas aqui preview é uma imagem gratuita, com marca d'água, de até 640 px (remove.bg: 0.25 megapixels sem marca d'água). Uma integração que nunca define size vai receber pré-visualizações com marca d'água; passe size=auto ou um nível pago para o resultado sem marca d'água.
Não afirmamos compatibilidade em nível de SDK. Três clientes de terceiros — o pacote removebg do PyPI, o pacote oficial remove.bg do npm e o removebg-cli — passaram em nossos testes em 22 de setembro de 2026, mas não fazemos testes de regressão versão a versão; clientes HTTP escritos à mão são o caminho que damos suporte.
shadow_type, shadow_opacity, add_shadow e semitransparency são aceitos e validados, mas nunca alteram a saída — como no remove.bg para objetos que não são carros; não existe um modelo específico para carros.
Cada chamada conta como uma imagem no limite da sua chave, de 40 imagens por minuto — o remove.bg permite 500. Trate o 429 com Retry-After ou fale com a gente para aumentar o limite.

2

Antes e depois

A mesma requisição em cada serviço.

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

Suporte a parâmetros

Parâmetro	Status	Observações
`image_file`	Igual	Upload multipart. JPG / PNG / WebP, até 20 MB (remove.bg: 22 MB).
`image_url`	Igual	URL pública da imagem, buscada do nosso lado com o mesmo limite de 20 MB.
`image_file_b64`	Igual	Imagem codificada em Base64 no corpo da requisição, igual ao remove.bg.
`size`	Diferente	Mesmos valores, mesmo padrão (preview) e mesmos limites de megapixels — mas aqui preview é uma imagem gratuita com marca d'água de até 640 px, e não 0.25 MP sem marca d'água. medium / hd / 4k / full / 50MP custam 1 crédito cada; auto usa o nível pago enquanto houver créditos.
`format`	Igual	auto / png / jpg / webp / zip — o zip contém color.jpg e alpha.png, como no remove.bg. Accept: application/json retorna o envelope base64. A saída em PNG é limitada a 10 megapixels.
`type, type_level`	Diferente	Aceito; type é mapeado para nossos próprios modelos. X-Type informa uma classe genérica — person, product, animal, car ou other — e type_level=2 / latest retornam as mesmas classes genéricas.
`crop, crop_margin`	Igual	Recorta no objeto principal com a mesma sintaxe de margem e o mesmo limite de 50% / 500 px.
`roi`	Igual	Região de interesse em pixels ou porcentagem, como no remove.bg.
`scale, position`	Igual	Escala do objeto (10%–100% ou original) e posição, como no remove.bg.
`channels`	Igual	rgba (padrão) ou alpha apenas para a máscara.
`bg_color`	Igual	Transparente por padrão; hex de 3 / 4 / 6 / 8 dígitos com ou sem #, ou um nome de cor.
`bg_image_file, bg_image_url`	Igual	Redimensionada para cobrir a saída e centralizada; não pode ser combinada com bg_color.
`add_shadow, shadow_type, shadow_opacity`	Sem efeito	Validado com os valores do remove.bg, mas nenhuma sombra é renderizada.
`semitransparency`	Sem efeito	Aceito; áreas semitransparentes são sempre tratadas automaticamente.

Todo parâmetro é validado com os intervalos de valores do próprio remove.bg, então um valor inválido vira um 400 invalid_parameter em vez de ser ignorado silenciosamente — exatamente como o remove.bg responde.

4

O que se comporta de forma diferente

Código de status 200 OK com os bytes da imagem, igual ao remove.bg — código que verifica == 200 continua funcionando. (O endpoint próprio do PixMiller, /api/v1/remove, responde 201 com JSON; este caminho de compatibilidade, deliberadamente, não.)

Corpo da resposta Os bytes da imagem, exatamente como no remove.bg. Envie Accept: application/json para receber o envelope base64 do remove.bg, ou format=zip para color.jpg mais alpha.png.

Response headers X-Credits-Charged, X-Width, X-Height, X-Type, X-Foreground-Top / -Left / -Width / -Height e X-RateLimit-Limit / -Remaining / -Reset são todos retornados. X-Type é uma classe genérica (person / product / animal / car / other), e não o vocabulário mais detalhado do remove.bg.

Erros Os erros usam o formato JSON:API do remove.bg: {"errors":[{"title":"…","code":"…"}]} — um array, então errors[0].title é lido igual a antes. Uma chave ausente é 403 auth_failed e uma chave errada, 403 invalid_api_key; saldo zerado é 402 e throttling é 429.

Créditos preview é gratuito; todo nível pago custa 1 crédito por imagem, cobrado somente depois que o resultado é obtido, então uma chamada que falha nunca custa um crédito. Não há cota mensal gratuita.

Limite de taxa 40 imagens por minuto por chave (remove.bg: 500). Cada chamada conta como uma imagem, e X-RateLimit-Limit / -Remaining / -Reset mostram essa cota por imagem; trate o 429 com Retry-After.

5

Como consultar seu saldo

O endpoint de conta informa o saldo de créditos restante da chave em data.attributes.credits, então uma verificação de saldo escrita para o remove.bg mantém o mesmo formato. Não há cota mensal gratuita, então free_calls é sempre 0.

GET /v1.0/account

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

6

Erros

400 invalid_parameter Um valor fora do intervalo do remove.bg para size / format / crop / scale / … ou uma fonte de imagem ausente; o title indica qual é o parâmetro.

400 file_too_large A imagem de entrada excede 20 MB.

400 unknown_foreground Não foi possível encontrar um primeiro plano na imagem.

402 insufficient_credits Um nível pago foi solicitado, mas o saldo está zerado. Nada é cobrado.

403 auth_failed / invalid_api_key O cabeçalho X-Api-Key está ausente (auth_failed) ou errado (invalid_api_key) — 403 como no remove.bg, não 401.

429 rate_limit_exceeded Limite de taxa excedido. Tente novamente depois do tempo indicado no cabeçalho Retry-After.

502 result_fetch_failed Não foi possível buscar o resultado no armazenamento. Nada foi cobrado — repita a requisição.

O código de status carrega o significado, e code usa o vocabulário do próprio remove.bg — um switch em errors[0].code continua funcionando.

Alternativa ao remove.bg Fale conosco