去背 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，以便在各類工具和伺服器端程式碼中使用。但這並不意味著可以把金鑰放在網頁中：任何人都能在網頁裡讀取它。
• 同一帳戶下的所有金鑰共用同一點數餘額。請在帳戶頁面為每個應用或環境分別建立金鑰，這樣撤銷其中一個時不會影響其他金鑰。
• 如果金鑰洩露，請立即在帳戶頁面撤銷它（會立即失效），然後建立一個新金鑰。我們只儲存每個金鑰的雜湊值，因此無法再次向你顯示金鑰。

故障排查