图片去背景 API 接口文档
兼容 remove.bg 的高清抠图 API：请求参数、响应格式与迁移差异。
POST https://removebgtool.net/v1.0/removebg
curl --fail-with-body --max-time 180 \
-H 'X-API-Key: YOUR_API_KEY' \
-F 'image_file=@image.jpg' \
-F 'size=auto' \
'https://removebgtool.net/v1.0/removebg' -o no-bg.png请求参数
发送 X-API-Key。image_file 使用 multipart/form-data；JSON 或 URL 编码请求体可使用 image_url、image_file_b64，且只能提供一个图片来源。crop 默认 false；format 默认 auto，透明结果选 PNG，不透明结果选 JPG。bg_color 支持 CSS 颜色名或 3/4/6/8 位十六进制。JPG 会将透明区域合成到白底。
| 能力 | 支持情况 |
|---|---|
| 图片输入 | JPG、PNG、WebP · 文件、HTTPS URL、base64 |
| 分辨率 | preview / small / regular · medium · hd · full / 4k · auto · 50MP |
| 输出 | PNG、JPG、WebP · auto · 二进制或 JSON |
| 图片选项 | crop、bg_color、type=auto、type_level=none、channels=rgba |
| 暂不支持 | ZIP、阴影、ROI、背景图片、前景分类、crop_margin、scale、position、仅 alpha 输出、半透明控制、OAuth |
请求参数
| 请求字段 | 默认值与可选值 |
|---|---|
| image_file / image_url / image_file_b64 | 只能提供一个图片来源。文件使用 multipart/form-data；image_url 必须为 HTTPS；image_file_b64 为带填充的普通 base64 字符串。 |
| size | 默认 preview。像素上限：preview/small/regular 为 0.25 MP；medium 为 1.5 MP；hd 为 4 MP；full/4k/auto 为 25 MP；50MP 为 50 MP。PNG 最高 10 MP，不放大图片。 |
| format | 默认 auto。支持 auto、png、jpg、webp，JPG 无法保留透明区域。 |
| crop | 默认 false，设为 true 可裁去空白边缘，不支持 crop_margin 参数。 |
| bg_color | 可选背景色。不传时，在支持透明的输出格式中保留透明背景。 |
URL 与 base64 输入
将示例 URL 替换为自己的 HTTPS 图片直链。base64 使用带填充的纯字符串，不带 data-URL 前缀。不要同时提交多个输入字段。
curl --fail-with-body --max-time 180 \
-H 'X-API-Key: YOUR_API_KEY' \
-F 'image_url=https://example.com/photo.jpg' \
-F 'format=png' \
'https://removebgtool.net/v1.0/removebg' -o result.png
# JSON input and JSON output
curl --fail-with-body --max-time 180 \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data '{"image_file_b64":"YOUR_PADDED_BASE64","format":"png"}' \
'https://removebgtool.net/v1.0/removebg'语言接入示例
这些是 HTTP 客户端示例，不是官方 SDK。API 密钥应放在服务器端配置中。
Python
import requests
with open('image.jpg', 'rb') as image:
response = requests.post(
'https://removebgtool.net/v1.0/removebg',
headers={'X-API-Key': 'YOUR_API_KEY'},
files={'image_file': image},
data={'size': 'auto'},
timeout=180,
)
response.raise_for_status()
with open('no-bg.png', 'wb') as output:
output.write(response.content)Node.js
import { readFile, writeFile } from 'node:fs/promises';
const form = new FormData();
form.append('image_file', new Blob([await readFile('image.jpg')]), 'image.jpg');
form.append('size', 'auto');
const response = await fetch('https://removebgtool.net/v1.0/removebg', {
method: 'POST',
headers: { 'X-API-Key': 'YOUR_API_KEY' },
body: form,
signal: AbortSignal.timeout(180000),
});
if (!response.ok) throw new Error(await response.text());
await writeFile('no-bg.png', Buffer.from(await response.arrayBuffer()));响应格式
HTTP 200 返回图片字节；指定 Accept: application/json 可获取 data.result_b64 和尺寸。响应头包含 X-Width、X-Height、X-Credits-Charged、X-Foreground-Top/Left/Width/Height、X-Request-ID。前景坐标基于归一化后的输入画布，不提供分类或 X-Type。GET /v1.0/account 返回 data.attributes.credits 和 api.free_calls（0）。
{
"data": {
"result_b64": "...",
"result_width": 625,
"result_height": 400,
"credits_charged": 1
}
}限制与差异
输入：≤22 MB、≤50 MP，宽高各为 33–9999 像素，单帧 JPG/PNG/WebP。HTTPS URL 必须是公开直链并使用 443 端口，不接受重定向或私有网络。size 默认 preview（0.25 MP）；medium=1.5 MP、hd=4 MP、full/4k/auto=25 MP、50MP=50 MP。PNG 和 auto 输出上限 10 MP，不放大原图。与 remove.bg 不同，auto 不会根据余额选择尺寸。
API 调用使用已有的账户积分。每张图当前的扣费可在控制台和 X-Credits-Charged 响应头中查看。预览与完整分辨率按同一单价扣费，不含额外的每月免费 API 额度。
错误与重试
400 输入或参数错误；402 积分不足；403 密钥或套餐无效；409 幂等冲突、处理中或已过期；415 不支持的请求编码；429 限流；502/503 上游故障或繁忙；504 超时。429/503 请遵循 Retry-After，临时 5xx 使用指数退避重试。密钥应仅保存在服务器端。
{
"errors": [
{
"title": "Insufficient credits.",
"code": "insufficient_credits"
}
]
}可选 Idempotency-Key：相同密钥、图片和参数，可在 10 分钟内重放成功结果而不重复扣费。重放会重复原 X-Credits-Charged，并附加 X-Idempotent-Replayed: true。处理中返回 409；失败或过期的键仍保留，发起新的计费请求需换新键。不带该请求头时，每次请求独立。客户端超时建议留足 180 秒。
迁移检查清单
1. 在支持 API 的套餐中创建密钥。2. 替换域名，保留 /v1.0/removebg 路径。3. 检查输入限制与未支持参数。4. 测试常用图片、错误处理和扣费。5. 再切换生产流量。本服务独立于 remove.bg。查看迁移指南 →
接口兼容不代表 AI 处理效果完全相同。迁移前请用自己的图片测试。