remove.bg API 遷移指南

1

先看這裡

不一樣的四件事。

size 預設為 preview，與 remove.bg 相同——但這裡的 preview 是最長邊 640 px 的免費浮水印圖（remove.bg：0.25 百萬像素、無浮水印）。從不設定 size 的整合會拿到帶浮水印的預覽圖；請傳 size=auto 或付費檔位以取得無浮水印的結果。
我們不宣稱 SDK 級相容。三個第三方用戶端——PyPI 的 removebg 套件、官方的 npm remove.bg 套件與 removebg-cli——在 2026 年 9 月 22 日通過了我們的測試，但我們不會逐版本對它們做回歸測試；自行撰寫的 HTTP 用戶端才是我們支援的路徑。
shadow_type、shadow_opacity、add_shadow 與 semitransparency 會被接受並驗證，但永遠不會改變輸出——與 remove.bg 對非車輛主體的行為一致；這裡沒有車輛專用模型。
每次呼叫以 1 張計入金鑰的限額：每分鐘 40 張（remove.bg 為 500 張）。遇到 429 請依 Retry-After 重試，或聯絡我們提高限額。

2

遷移前後對照

同一個請求分別打給兩家服務。

remove.bg

1curl -X POST "https://api.remove.bg/v1.0/removebg" \2  -H "X-Api-Key: REMOVEBG_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png

PixMiller

1curl -X POST "https://api.pixmiller.com/v1.0/removebg" \2  -H "X-Api-Key: PIXMILLER_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png6# 200 OK → image bytes, written straight to out.png7# X-Credits-Charged: 1   X-Width: 1200   X-Height: 1600   X-Type: product

3

參數支援情況

參數	狀態	說明
`image_file`	一致	Multipart 上傳。JPG / PNG / WebP，最大 20 MB（remove.bg：22 MB）。
`image_url`	一致	公開可存取的圖片 URL，由我們這邊抓取，同樣限制 20 MB。
`image_file_b64`	一致	請求主體裡的 base64 圖片，與 remove.bg 相同。
`size`	有差異	取值、預設值（preview）與百萬像素上限都相同——但這裡的 preview 是最長邊 640 px 的免費浮水印圖，而不是 0.25 MP 的無浮水印圖。medium / hd / 4k / full / 50MP 每張各 1 點數；只要還有點數，auto 就會走付費檔位。
`format`	一致	auto / png / jpg / webp / zip——zip 內含 color.jpg 與 alpha.png，與 remove.bg 一致。Accept: application/json 會回傳 base64 封裝。PNG 輸出上限為 1000 萬像素。
`type, type_level`	有差異	接受該參數；type 會對應到我們自己的模型。X-Type 回傳粗略分類——person、product、animal、car 或 other——type_level=2 與 latest 也回傳同樣的粗略分類。
`crop, crop_margin`	一致	依主體裁切，margin 語法與 50% / 500 px 上限都與 remove.bg 相同。
`roi`	一致	以像素或百分比指定感興趣區域，與 remove.bg 相同。
`scale, position`	一致	主體縮放（10%–100% 或 original）與位置，與 remove.bg 相同。
`channels`	一致	rgba（預設）或 alpha（只取遮罩）。
`bg_color`	一致	預設透明；支援帶或不帶 # 的 3 / 4 / 6 / 8 位十六進位色碼，或顏色名稱。
`bg_image_file, bg_image_url`	一致	等比放大填滿輸出並置中；不能與 bg_color 併用。
`add_shadow, shadow_type, shadow_opacity`	無效果	會依 remove.bg 的取值驗證，但永遠不會產生任何陰影。
`semitransparency`	無效果	接受該參數；半透明區域一律自動處理。

每個參數都依 remove.bg 自己的取值範圍驗證，無效值會回傳 400 invalid_parameter 而不是被靜默忽略——與 remove.bg 的回應完全一致。

4

哪些行為不同

狀態碼 200 OK，回應主體就是圖片位元組，與 remove.bg 一致——斷言 == 200 的程式可以照舊。（PixMiller 自家的 /api/v1/remove 端點回傳的是 201 加 JSON；這條相容路徑刻意不這麼做。）

回應主體圖片位元組，與 remove.bg 完全一樣。送出 Accept: application/json 可改成 remove.bg 的 base64 封裝，或用 format=zip 取得 color.jpg 加 alpha.png。

Response headers X-Credits-Charged、X-Width、X-Height、X-Type、X-Foreground-Top / -Left / -Width / -Height 以及 X-RateLimit-Limit / -Remaining / -Reset 全部都會回傳。X-Type 是粗略分類（person / product / animal / car / other），而不是 remove.bg 更細的詞彙。

錯誤錯誤沿用 remove.bg 的 JSON:API 結構：{"errors":[{"title":"…","code":"…"}]}——是陣列，所以 errors[0].title 的讀法與以前相同。缺少金鑰為 403 auth_failed，金鑰錯誤為 403 invalid_api_key，餘額為零為 402，觸發限流為 429。

點數 preview 免費；每個付費檔位每張 1 點數，而且只在結果取回之後才扣款，因此失敗的呼叫永遠不會消耗點數。這裡沒有每月免費額度。

速率限制每個金鑰每分鐘 40 張（remove.bg：500 張）。每次呼叫計為 1 張，X-RateLimit-Limit / -Remaining / -Reset 反映的就是這份以張計算的額度；遇到 429 請依 Retry-After 重試。

5

查詢餘額

account 端點會在 data.attributes.credits 下回報該金鑰的剩餘點數餘額，因此照 remove.bg 寫的餘額檢查結構不變。這裡沒有每月免費額度，所以 free_calls 恆為 0。

GET /v1.0/account

1curl "https://api.pixmiller.com/v1.0/account" \2  -H "X-Api-Key: PIXMILLER_KEY"

6

錯誤

400 invalid_parameter size / format / crop / scale 等參數的值超出 remove.bg 的範圍，或缺少圖片來源；title 會寫明是哪個參數。

400 file_too_large 輸入圖片超過 20 MB。

400 unknown_foreground 圖片中找不到前景主體。

402 insufficient_credits 請求了付費檔位，但餘額為零。不會扣點數。

403 auth_failed / invalid_api_key X-Api-Key 標頭缺少（auth_failed）或錯誤（invalid_api_key）——與 remove.bg 一樣回傳 403 而不是 401。

429 rate_limit_exceeded 超出速率限制。請依 Retry-After 標頭退避後重試。

502 result_fetch_failed 無法從儲存空間取回結果。未扣任何點數——請重試該請求。

語意由狀態碼承載，code 沿用 remove.bg 自己的詞彙——依 errors[0].code 分支的程式可以照舊。

remove.bg 替代方案聯絡我們