背景去除 API：一个请求进，处理好的 PNG 出。

发送图片

POST /v1/remove 支持四种方式传入图片。任选其一发送；如果一个请求包含多种，优先使用 image_file，其次是 image_file_b64，然后是 image_url，最后是原始请求体。这些示例从 REMOVEBG_API_KEY 环境变量读取密钥（用 export REMOVEBG_API_KEY=… 设置）；注意要使用双引号，这样 shell 才会替换变量。

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' \
  -o photo-no-bg.png

每个示例都会把响应体保存为文件。只有状态码为 200 时，该文件才是图片；参见处理响应。

处理响应

大多数单张图片会在同一响应中返回处理结果。当队列异常繁忙、某张图片耗时超过约 55 秒时，你会收到 202 Accepted 和一个任务 id。任务会继续运行：用该 id 获取结果。重新发送图片会创建第二个任务，并可能多消耗一个点数。

完整示例

处理已完成的图片、202、失败的任务以及本地超时。图片只发送一次，只对安全的状态查询进行重试。

import os
import time
import uuid

import requests

API = "https://removebackground.dev"
KEY = os.environ["REMOVEBG_API_KEY"]  # keep the key on your server
EXT = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}


def save(res, stem):
    """Save an image response with the right extension; raise on anything else."""
    mime = res.headers.get("Content-Type", "").split(";")[0]
    if res.status_code != 200 or mime not in EXT:
        raise RuntimeError(f"HTTP {res.status_code}: {res.text[:500]}")
    path = stem + EXT[mime]
    with open(path, "wb") as f:
        f.write(res.content)
    return path


def remove_background(image_url, stem="result", max_wait=300):
    s = requests.Session()
    s.headers["x-api-key"] = KEY

    # One key per image: resending with the same key returns the same job, never a second
    # charge, so this POST is safe to retry after a timeout or a dropped connection.
    idem = {"Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        try:
            res = s.post(f"{API}/v1/remove", data={"image_url": image_url}, headers=idem, timeout=(10, 120))
            break
        except requests.ConnectionError:
            if attempt == 2:
                raise
            time.sleep(2)
    if res.status_code != 202:
        return save(res, stem)  # 200 = the image; anything else raises

    # 202: still processing. Wait for the same job; never send the image again.
    job_id = res.json()["id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        time.sleep(2)  # the API sends Retry-After: 2
        res = s.get(f"{API}/v1/jobs/{job_id}/result", timeout=30)
        if res.status_code == 409 and res.json()["error"]["code"] == "not_ready":
            continue
        return save(res, stem)  # the image, or the job's own error
    raise TimeoutError(f"Job {job_id} is still running. Check it later at /v1/jobs/{job_id}.")


print(remove_background("https://example.com/photo.jpg"))

• 停止你的脚本并不会停止任务；任务仍可能完成并被扣费。其结果会出现在你的作品库中。
• 超时时间由你自行决定，并非我们的承诺；大多数图片几秒内即可完成。
• 兼容 remove.bg 的端点行为不同：它从不返回 202（见下文）。

批次完整流程

1. 提交

curl -X POST https://removebackground.dev/v1/batch \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "image_urls": ["https://example.com/front.jpg", "https://example.com/back.jpg"], "format": "png", "size": "hd" }'

最多 100 个公开图片 URL，以及任意 /v1/remove 选项。上面的两个占位 URL 如果是真实图片，最多会消耗 2 点数。响应会立即返回：

202 Accepted
{
  "id": "3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77",
  "status": "queued",
  "total": 2,
  "invalid": 0,
  "duplicates": 0,
  "status_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77"
}

invalid 统计不是 http(s) URL 的条目，duplicates 统计重复项；两者都会被丢弃，且不会扣费。请保存 id：重启后要靠它重新获取任务。

2. 轮询任务

每隔几秒调用 GET /v1/jobs/:id，直到 done 为 true。status 从 queued 变为 processing，最终为 succeeded、partial（部分图片失败）或 failed。正在重试的条目显示为 retrying。

{
  "id": "3f6c2a9e-…",
  "status": "partial",
  "done": true,
  "total": 2, "succeeded": 1, "failed": 1, "skipped": 0,
  "credits_charged": 1,
  "items": [
    { "position": 0, "input": "https://example.com/front.jpg", "status": "succeeded",
      "removal_id": "…", "width": 1600, "height": 1200, "format": "png",
      "result_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-…/result?item=0" },
    { "position": 1, "input": "https://example.com/back.jpg", "status": "failed",
      "error": { "code": "fetch_failed", "message": "…" } }
  ]
}

3. 下载每个结果

对每个成功的条目调用 GET /v1/jobs/:id/result?item=N（或使用其 result_url）。item 是从零开始的 position。位置按你的列表在移除无效和重复 URL 之后排列，因此当任一计数大于 0 时，请按 input 而不是按索引匹配结果。

• 一旦 done 为 true，该批次就不再计入 3 个未完成批次的限制。
• API 没有取消端点、webhook 或 ZIP 下载。在批量处理页面启动的批次可以在该页面取消或下载为 ZIP。

重试、重复与计费

发送 Idempotency-Key，重试就不会重复扣费。在 POST /v1/remove 或 POST /v1/batch 中添加 Idempotency-Key 请求头（任意唯一字符串，最长 255 个字符，例如 UUID），每张图片或每个批次一个键。如果你用相同的键再次发送相同的请求，会得到第一次请求创建的任务，并带有 Idempotent-Replayed: true：不会创建新任务，也不会再次扣费，即使第一次请求仍在运行。相同的键配合不同的图片或选项会返回 409 idempotency_key_reused。键归属于你的账户，不会过期。

不带键时，每个 POST 都会创建一个新任务，每个成功的任务消耗 1 点数（兼容 remove.bg 的 POST /v1.0/removebg 不支持键）。读取任务（GET /v1/jobs/…）始终免费，可以放心重复调用。

IDEMPOTENCY_KEY=$(uuidgen)   # one per image; send the same one on every retry

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F 'image_file=@photo.jpg' \
  -o photo-no-bg.png

哪些情况消耗点数

何时重试

限制与存储

结果保留多久

每个结果在生成后都会私密保存在你的账户中 48 小时，之后删除。在此之前，你可以通过 GET /v1/jobs/:id/result 或在作品库中免费再次下载。 此后，结果链接会返回 410 result_unavailable；重新处理图片会创建新任务。图片删除后，任务状态记录仍可读取。上传文件的处理方式请参阅隐私政策；我们不会使用你的图片训练模型。

安全

请将 API 密钥保存在你自己控制的服务器上。不要把它放进浏览器代码、移动应用、公开代码仓库或 URL 中。如需让你的用户去除背景，请通过你的后端转发他们的图片，并在后端添加你自己的登录验证和消费限额。

• API 允许 CORS，以便在各类工具和服务器端代码中使用。但这并不意味着可以把密钥放在网页中：任何人都能在网页里读取它。
• 同一账户下的所有密钥共用同一点数余额。请在账户页面为每个应用或环境分别创建密钥，这样撤销其中一个时不会影响其他密钥。
• 如果密钥泄露，请立即在账户页面撤销它（会立即失效），然后创建一个新密钥。我们只存储每个密钥的哈希值，因此无法再次向你显示密钥。

故障排查