Background Remover API 开发者文档

专为 remove.bg® 设计的高性能无缝平替 API。通过 multipart 表单或公开 URL 发送图片，即可在 200ms 内直接接收带有 Alpha 透明通道的高精度二进制 PNG 图片。

# Base URL & 身份鉴权

所有 API 请求必须通过 HTTPS 发起。请在请求头中传入您的 API 密钥： X-Api-Key header.

# Base URL

https://backgroundremoverapi.com

# 身份鉴权 Header

X-Api-Key: YOUR_API_KEY

* 在测试或评估阶段，您可在在线测试场中免配置 API Key 快速体验沙箱调用。

POST /v1.0/removebg

返回值：image/png (二进制数据流)

移除上传图片文件或公开图片 URL 中的背景。接口直接返回带有透明通道的原生二进制 PNG 字节流。

请求体参数 (multipart/form-data)

参数名称	类型	必填	描述说明
image_file	binary	二选一必填*	原始图像文件（支持 JPEG、PNG、WEBP）。*必须提供 `image_file` 或 `image_url` 两者之一。
image_url	string	二选一必填*	待处理图像的公开可访问 HTTPS 图片链接。
size	string	选填	`auto` (default), `preview`, or `full`。与 remove.bg 官方尺寸过滤器完全保持一致。
format	string	选填	`auto` or `png` (默认)。返回标准 32 位 RGBA 透明 PNG。

响应头信息

响应头与 remove.bg 官方 SDK 的遥测检测规范保持完全一致：

Content-Type: image/png

X-Width: 1200

X-Height: 800

X-Credits-Charged: 1

X-Processing-Time-Ms: 142

X-Dropin-Provider: bgremoverapi

# 多语言集成代码示例

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "size=auto" \
  https://backgroundremoverapi.com/v1.0/removebg \
  -o no-bg.png

import requests

response = requests.post(
    "https://backgroundremoverapi.com/v1.0/removebg",
    files={"image_file": open("photo.jpg", "rb")},
    data={"size": "auto"},
    headers={"X-Api-Key": "YOUR_API_KEY"},
)

if response.status_code == requests.codes.ok:
    with open("no-bg.png", "wb") as out:
        out.write(response.content)
    print(f"Saved! Processed in {response.headers.get('X-Processing-Time-Ms')}ms")
else:
    print("Error:", response.status_code, response.text)

const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');

const formData = new FormData();
formData.append('image_file', fs.createReadStream('photo.jpg'));
formData.append('size', 'auto');

axios({
  method: 'post',
  url: 'https://backgroundremoverapi.com/v1.0/removebg',
  data: formData,
  responseType: 'arraybuffer',
  headers: {
    ...formData.getHeaders(),
    'X-Api-Key': 'YOUR_API_KEY',
  },
  encoding: null
})
.then((response) => {
  fs.writeFileSync('no-bg.png', response.data);
  console.log('Finished!');
})
.catch((error) => {
  console.error('Request failed:', error);
});

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://backgroundremoverapi.com/v1.0/removebg');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Api-Key: YOUR_API_KEY'));
curl_setopt($ch, CURLOPT_POSTFIELDS, array(
    'image_file' => new CURLFile('photo.jpg'),
    'size' => 'auto'
));

$result = curl_exec($ch);
curl_close($ch);

file_put_contents('no-bg.png', $result);
echo "Transparent PNG saved successfully!\n";
?>

# HTTP 状态码与异常处理

HTTP 状态码	说明	响应格式
200 OK	图像前景抠图成功，响应体包含纯二进制 PNG 数据流。	image/png
400 Bad Request	缺少图片文件/URL，或上传的文件无法被解析为图片。	application/json
402 Payment Required	账户 API 调用额度已耗尽。	application/json
403 Forbidden	未提供 X-Api-Key 请求头，或密钥无效/已被撤回。	application/json
429 Too Many Requests	并发请求频率超过所选方案限制。	application/json

GET /v1.0/account

查询账户剩余额度与调用配额。数据结构与 remove.bg 官方 account 响应体完全一致。

{
  "data": {
    "attributes": {
      "credits": {
        "total": 500,
        "subscription": 500,
        "payg": 0
      },
      "api": {
        "free_calls": 50,
        "sizes": "all"
      }
    }
  }
}