熟悉的 HTTP 请求格式只是起点。切换生产流量前，先按照这份清单验证图片效果与集成流程。
我们的生产 API 已在 Cloudflare 上线。D1 负责原子积分预留，私有 R2 保存重试结果，只有请求后处理时才会调用 Cloudflare Images。
迁移检查清单
1. 盘点正在使用的请求
列出当前输入方式、输出格式、尺寸和编辑参数。本服务支持文件、HTTPS URL 和普通 base64，但未实现 remove.bg 的全部选项。密钥只放在服务器端，并在支持 API 的套餐中创建新密钥。
2. 更换端点和密钥
对支持的 HTTP 请求，保留结构并替换源站地址与 X-API-Key。若库写死 remove.bg 域名，使用它的接口覆盖选项，或直接通过 HTTP 客户端调用。不要向本服务发送 remove.bg 密钥。
迁移前后：单张文件请求
原 remove.bg 请求
curl -H 'X-API-Key: REMOVE_BG_KEY' -F 'image_file=@image.jpg' -F 'size=auto' 'https://api.remove.bg/v1.0/removebg' -o no-bg.pngRemoveBG 正式请求
curl --fail-with-body -H 'X-API-Key: NEW_REMOVEBG_KEY' -F 'image_file=@image.jpg' -F 'size=auto' -F 'format=png' 'https://removebgtool.net/v1.0/removebg' -o no-bg.png两个示例都使用 multipart 表单和 X-API-Key，但密钥必须重新申请。目标请求明确设置了 size=auto 和 PNG；省略 size 与 format 时返回原尺寸透明 PNG。API 已正式开放，切换流量前仍应使用自己的常见图片测试。
切换前需要核对的差异
- 只能提供一种输入：image_file、image_url 或普通 base64 的 image_file_b64；输出格式支持 auto、png、jpg、webp，不支持 ZIP 响应。
- type=auto、type_level=none 和 channels=rgba 是这些字段唯一接受的值。shadow、bg_image_url、ROI、crop_margin、scale、position 等非空参数会报错。
- 省略 size 时返回原尺寸。只有需要限制像素时才设置具体 size，并核对响应的实际尺寸和 Content-Type。
- 正常成功返回图片字节；请求 Accept: application/json 时返回 data.result_b64 和尺寸。错误使用 errors[].title 与 errors[].code。
# Generate one ID per image; reuse it when retrying this request.
REQUEST_ID="$(uuidgen)"
curl --fail-with-body --max-time 180 \
-H 'X-API-Key: YOUR_API_KEY' \
-H "Idempotency-Key: $REQUEST_ID" \
-F 'image_file=@image.jpg' \
'https://removebgtool.net/v1.0/removebg' -o no-bg.png3. 测试前核对参数
兼容指支持相应请求结构，不代表分割结果相同。当前 type 只能为 auto，type_level 只能为 none，channels 只能为 rgba。非空的未支持参数会明确拒绝，不会静默忽略。
| 请求字段 | 本服务支持情况 |
|---|---|
| image_file / image_url / image_file_b64 | 只能选择 image_file、image_url 或 image_file_b64 中的一种输入。 |
| format | 支持 auto、png、jpg、webp，不支持 ZIP。 |
| size | 像素上限因输出格式而异，请核对尺寸表与输出限制。 |
| crop / bg_color | 支持 crop=true/false 和 bg_color。 |
| type / type_level / channels | 分别仅支持 auto / none / rgba。 |
| bg_image_url / shadow / roi / crop_margin / scale / position | 不支持背景图、阴影、ROI、裁切边距、缩放或位置。 |
4. 检查响应和计费
保存前读取响应 Content-Type。默认返回图片字节，按需返回含 result_b64 的 JSON。检查 X-Credits-Charged 与 X-Request-ID。积分属于本服务账户，remove.bg 的密钥和余额不能转移。本 API 的预览与完整分辨率使用相同的单张扣费。
处理响应、错误和计费
保存文件前先检查状态码和响应格式。保留 X-Request-ID 便于排查，成功时读取 X-Credits-Charged。API 按单独配置的每张费率从账户积分扣费，网站免费预览不适用。
| 响应 | 含义 | 接入时的处理 |
|---|---|---|
| 400 | 缺少图片、输入无效或包含不支持的参数。 | 读取 errors[].code，只传一种图片来源，并移除不支持的字段。 |
| 403 | 缺少或无效的 API 密钥，或账户未获得 API 权限。 | 使用符合条件的账户重新生成密钥，不要转发 remove.bg 密钥。 |
| 402 | insufficient_credits，积分不足。 | 补足余额，并核对当前 API 单张扣费后再重试。 |
| 409 | 请求仍在处理，或 Idempotency-Key 冲突、重放期限已过。 | 读取具体错误码，只在响应建议时使用同一密钥重试。 |
| 429 | 超过频率或并发限制；响应带 Retry-After。 | 按 Retry-After 退避，不要立即重复请求。 |
| 502 / 503 / 504 | 上游失败、服务忙、运行环境不可用或超时。 | 读取 errors[].code 与 X-Request-ID，再决定排查或重试。 |
5. 运行代表性测试集
测试常用商品与人像、低对比度边缘、每种输出格式，以及超大文件、无效密钥、未支持参数和积分不足。验证 409、429、超时与处理失败的逻辑，并保留请求 ID 便于排查。
可选 Idempotency-Key：相同密钥、图片和参数，可在 10 分钟内重放成功结果而不重复扣费。重放会重复原 X-Credits-Charged，并附加 X-Idempotent-Replayed: true。处理中返回 409；失败或过期的键仍保留，发起新的计费请求需换新键。不带该请求头时，每次请求独立。客户端超时建议留足 180 秒。
6. 渐进切换，保留回退方式
先将少量自有工作负载切到新接口，观察成功率、图片质量与积分消耗，符合需求后再逐步放量。验证期间保留旧配置。流量分配和回滚由你的应用管理，不是本服务的自动切换功能。
切换生产流量前，先验收这几项
remove.bg 官方 API 页面公告：自 2026 年 12 月 1 日起，背景移除服务向 Leonardo.Ai 迁移。这不代表 RemoveBG 是官方接替服务；网页版向 Canva 迁移与 API 迁移需要分别判断。
官方资料核对日期:
查看 remove.bg 官方 API 公告| 检查项目 | 当前实现的要求 | 建议验收方式 |
|---|---|---|
| 输入方式 | image_file、image_url、image_file_b64 只能三选一。开发者 API 的图片数据上限为 22 MiB；网页上传入口另有单张 3 MB 限制。 | 分别测试业务中会用到的输入类型。不能仅凭返回 HTTP 响应，就认定处理的是预期图片。 |
| 默认值与输出 | 省略 size 与 format 时返回原尺寸透明 PNG。显式 size 用于限制像素上限；格式支持 auto、png、jpg、webp，不支持 ZIP。 | 核对 Content-Type、实际像素尺寸和透明通道。更大的尺寸上限不等于承诺放大原图。 |
| 编辑参数 | type、type_level、channels 分别只接受 auto、none、rgba。shadow、bg_image_url 等非空的未支持参数会返回错误。 | 主动移除不支持的设置，不要假定系统已静默应用；用样图核对裁切和背景颜色。 |
| 失败与扣费 | 应用需要处理认证、积分不足、冲突、限流和图像处理失败。网页版免费预览不等同于 API 免费调用。 | 用真实请求查看 X-Request-ID、X-Credits-Charged。根据完整 API 文档确认重试和幂等处理，再逐步增加流量。 |
生产 API 已正式开放。这份清单依据项目内的请求解析代码整理；增加流量前仍需验证自己的 SDK、图片效果、时延和所需容量。
关于在线抠图，你可能还想问
RemoveBG API 能直接替换 remove.bg API 吗？
不能直接替换。RemoveBG 接收 image_file、image_url 或 image_file_b64，但默认值和支持的编辑参数不同。请逐项映射请求字段并测试实际响应。
原来的 remove.bg API 密钥能继续使用吗？
不能。请创建 RemoveBG 账户并在 API Keys 中生成新密钥。原账户、余额和密钥不会导入。
可以向当前部署发送付费高清 API 流量吗？
可以。生产 API 已正式开放。请创建 RemoveBG API 密钥，测试所需参数和输出，再逐步切换流量。
RemoveBG 是独立服务，与 remove.bg、Canva 或 Leonardo.Ai 无关联。原有账户、积分和 API 密钥无法迁入。