remove.bg API 迁移指南

1

先看这里

不一样的四件事。

size 默认为 preview，与 remove.bg 一致——但这里的 preview 是最长边 640 px 的免费水印图（remove.bg：0.25 MP 无水印）。从不设置 size 的集成会拿到带水印预览图；请传 size=auto 或付费档获取无水印结果。
我们不承诺 SDK 级兼容。三个第三方客户端——PyPI 的 removebg 包、npm 官方 remove.bg 包和 removebg-cli——在 2026 年 9 月 22 日通过了我们的测试，但我们不会逐版本对它们做回归测试；自己编写的 HTTP 客户端才是我们支持的路径。
shadow_type、shadow_opacity、add_shadow 与 semitransparency 接受并校验，但永远不会改变输出——与 remove.bg 对非车辆图片的行为一致；这里没有车辆专用模型。
每次调用按 1 张计入 key 的限额：每分钟 40 张（remove.bg 为 500 张）。遇到 429 请按 Retry-After 重试，或联系我们提高限额。

2

迁移前后对照

同一个请求分别打给两家服务。

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

参数支持情况

参数	状态	说明
`image_file`	一致	Multipart 上传。JPG / PNG / WebP，最大 20 MB（remove.bg：22 MB）。
`image_url`	一致	公开可访问的图片 URL，由我们这边抓取，同样限制 20 MB。
`image_file_b64`	一致	请求体里的 base64 图片，与 remove.bg 相同。
`size`	有差异	取值、默认值（preview）和像素上限都相同——但 preview 是最长边 640 px 的免费水印图，而不是 0.25 MP 无水印图。medium / hd / 4k / full / 50MP 每张 1 点；auto 在有点数时走付费档。
`format`	一致	auto / png / jpg / webp / zip——zip 内含 color.jpg 与 alpha.png，与 remove.bg 一致。Accept: application/json 返回 base64 信封。PNG 输出上限 1000 万像素。
`type, type_level`	有差异	接受该参数；type 会映射到我们自己的模型。X-Type 返回粗分类（person / product / animal / car / other），type_level=2 与 latest 返回同样的粗分类。
`crop, crop_margin`	一致	按主体裁切，margin 语法与 50% / 500 px 上限均与 remove.bg 一致。
`roi`	一致	以像素或百分比指定感兴趣区域，与 remove.bg 一致。
`scale, position`	一致	主体缩放（10%–100% 或 original）与位置，与 remove.bg 一致。
`channels`	一致	rgba（默认）或 alpha（只返回蒙版）。
`bg_color`	一致	默认透明；支持带或不带 # 的 3 / 4 / 6 / 8 位 hex，或颜色名。
`bg_image_file, bg_image_url`	一致	等比铺满输出并居中；不能与 bg_color 同时使用。
`add_shadow, shadow_type, shadow_opacity`	无效果	按 remove.bg 的取值校验，但不会渲染任何阴影。
`semitransparency`	无效果	接受该参数；半透明区域始终自动处理。

每个参数都按 remove.bg 自己的取值范围校验，非法值返回 400 invalid_parameter 而不是被静默忽略——与 remove.bg 的应答完全一致。

4

哪些行为不同

状态码 200 OK，响应体就是图片二进制，与 remove.bg 一致——断言 == 200 的代码可以照旧。（PixMiller 自家的 /api/v1/remove 端点返回的是 201 + JSON；这条兼容路径刻意不这么做。）

响应体直接返回图片字节，与 remove.bg 完全一样。发送 Accept: application/json 可改为 remove.bg 的 base64 信封，format=zip 则返回 color.jpg 加 alpha.png。

响应头 X-Credits-Charged、X-Width、X-Height、X-Type、X-Foreground-Top / -Left / -Width / -Height 以及 X-RateLimit-Limit / -Remaining / -Reset 全部返回。X-Type 是粗分类（person / product / animal / car / other），而不是 remove.bg 更细的词表。

错误错误沿用 remove.bg 的 JSON:API 形状：{"errors":[{"title":"…","code":"…"}]}——是数组，所以 errors[0].title 的读法和以前一样。缺少 key 为 403 auth_failed，key 错误为 403 invalid_api_key，余额为空为 402，限速为 429。

点数 preview 免费；每个付费档每张 1 点，且只在结果取回之后才扣点，所以失败的调用永远不会扣点。没有每月免费额度。

限速每个 key 每分钟 40 张（remove.bg：500 张）。每次调用计为 1 张，X-RateLimit-Limit / -Remaining / -Reset 反映的就是这份按张计的额度；遇到 429 请按 Retry-After 重试。

5

查询余额

account 端点在 data.attributes.credits 下返回该 key 的剩余点数，因此按 remove.bg 写的余额检查形状不变。没有每月免费额度，所以 free_calls 恒为 0。

GET /v1.0/account

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

6

错误

400 invalid_parameter size / format / crop / scale 等参数的值超出 remove.bg 的取值范围，或缺少图片来源；title 里会写明是哪个参数。

400 file_too_large 输入图片超过 20 MB。

400 unknown_foreground 图片中找不到前景主体。

402 insufficient_credits 请求了付费档但余额为空。不会扣点。

403 auth_failed / invalid_api_key X-Api-Key 请求头缺失（auth_failed）或错误（invalid_api_key）——与 remove.bg 一样返回 403 而不是 401。

429 rate_limit_exceeded 超出限速。请按 Retry-After 响应头退避后重试。

502 result_fetch_failed 无法从存储中取回结果。未扣点——请重试该请求。

语义由状态码承载，code 用的是 remove.bg 自己的词表——按 errors[0].code 分支的代码可以照旧。

remove.bg 替代方案联系我们