API 文檔

快速開始

第一次請求只需要 input.image_base64。省略 input.output 時，繼續回傳兼容舊用戶端的原尺寸透明結果。

curl --request POST   --url https://removezero.com/api/v1/remove-background   --header "Authorization: Bearer ${REMOVEZERO_API_KEY}"   --header "Content-Type: application/json"   --header "Idempotency-Key: image-2026-08-28-0001"   --data '{"input":{"image_base64":"BASE64_IMAGE_DATA"}}'

使用 Bearer Key 驗證

在個人帳戶建立 API Key，並在每次請求的 Authorization 請求標頭中傳送。

Authorization: Bearer rz_live_your_api_key

• 把 Key 儲存在伺服器環境變量或金鑰管理工具中。
• 不要把 Key 放進瀏覽器程式碼、移動端應用程式包、擴展、URL、公開程式碼儲存庫或記錄。
• 條件允許時，為不同服務或環境使用不同 Key。
• Key 可能洩露時立即撤銷並更換。

只從伺服器調用

推薦路徑是：瀏覽器或用戶端 → 你的伺服器 → RemoveZero API。Bearer Key 可以授權付費處理，公開用戶端無法安全儲存它。服務端付費請求必須省略 Origin 請求標頭。

傳送去背請求

從伺服器傳送一份嚴格驗證的 JSON 請求。必需請求標頭會在保留點數和處理圖片之前完成驗證。

POST https://removezero.com/api/v1/remove-background
Authorization: Bearer rz_live_your_api_key
Content-Type: application/json
Idempotency-Key: order-2026-08-25-0001

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA"
  }
}

• Content-Type 必須是 application/json，可以帶 charset 參數。
• Content-Encoding 必須省略或為 identity；不接受壓縮請求內容。
• 不要傳送 Origin 請求標頭。
• Idempotency-Key 長度為 1–128，只能使用字母、數字、句點、下划線、冒號和連字元。
• image_base64 必須是標準 Base64 圖片位元組，不能帶 data:image/... 前綴。

自訂輸出

output 對象可省略。它只在一次去背推理後調整畫布，因此整個請求仍只消耗 1 點數。

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA",
    "output": {
      "format": "webp",
      "background": "#ffffff",
      "width": 1600,
      "height": 1600,
      "padding_ratio": 0.08
    }
  }
}

固定 contain + center 規則

fit 不是請求字段。RemoveZero 始終保持主體比例，並把主體完整放入可用畫布。

• 主體完整可見並居中。
• 不裁切、不拉伸。
• 剩餘畫布使用透明或指定顏色填充。
• 不支援 cover、智慧裁切、gravity 定位或任意坐標。

向後兼容

現有用戶端可以省略 input.output，只傳送 input.image_base64。需要自訂格式、背景、畫布或留白時再新增 output。

成功響應

成功處理會回傳 HTTP 200，並消耗 1 點數。輸出包含準確的內容類型、畫布尺寸和可由伺服器解碼的 Base64 資料。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "id": "REQUEST_ID",
  "status": "COMPLETED",
  "output": {
    "ok": true,
    "content_type": "image/webp",
    "width": 1600,
    "height": 1600,
    "output_base64": "BASE64_IMAGE_RESULT"
  },
  "usage": {
    "units": 1,
    "credits_used": 1
  }
}

解碼結果

1. 確認 HTTP 200、ok: true 和 status: COMPLETED。
2. 讀取 output.content_type，並且只接受 image/png 或 image/webp。
3. 對 output.output_base64 解碼一次，再按內容類型儲存。
4. 請求了尺寸時，核對 output.width 和 output.height。

結果以內聯資料回傳，不提供永久 URL。需要長期儲存或交付時，應由你的應用程式儲存解碼後的位元組。

import { writeFile } from "node:fs/promises";

const payload = await response.json();

if (!response.ok || payload.ok !== true || payload.status !== "COMPLETED") {
  throw new Error(payload.error?.code ?? "REMOVEZERO_REQUEST_FAILED");
}

const { content_type: type, output_base64: base64 } = payload.output ?? {};
const extension = type === "image/png" ? "png" : type === "image/webp" ? "webp" : null;

if (!extension || typeof base64 !== "string") {
  throw new Error("REMOVEZERO_OUTPUT_INVALID");
}

await writeFile(`removezero-result.${extension}`, Buffer.from(base64, "base64"));

計費與點數返還

每次請求處理一張圖片。RemoveZero 會驗證請求、以不可分割方式保留 1 點數，並且只在去背和指定輸出都成功後結算。輸出自訂不會增加推理次數或額外消耗點數。

點數使用流程

如果暫時無法確認請求或返還，API 會回傳 REFUND_PENDING、請求 ID 和 Retry-After: 30。請保留同一個 Idempotency-Key，不要用新 Key 重複提交同一張圖片。

HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "REFUND_PENDING"
  },
  "request_id": "REQUEST_ID"
}

冪等與重試

Idempotency-Key 綁定完整的序列化 JSON 請求內容，包括圖片和所有已傳送的 output 字段。請同時保留原始請求位元組和 Key。

• 相同 Key + 完全相同請求內容：可以安全重試，不會二次保留點數或重複處理。
• 相同 Key + 請求內容改變：回傳 409 IDEMPOTENCY_CONFLICT。
• 終態請求再次使用相同 Key：回傳 409 IDEMPOTENCY_REPLAY_UNAVAILABLE；不會重放 Base64 結果。
• 新 Key：新的請求，可能再次保留 1 點數。
• 即使 JSON 語義相同，空格、字段順序或預設字段寫法變化也可能被視為不同請求。

Retry-After 規則

429 RATE_LIMITED

等待 60 秒，再用完全相同的請求內容和 Key 重試。

503 REFUND_PENDING

等待 30 秒，再用完全相同的請求內容和 Key 重試。

503 UPSTREAM_BUSY

等待 10 秒；只有確實發起新嘗試時才使用新 Key。

網路超時或 API_UNAVAILABLE

把結果視為未知，保留原始請求內容和 Key 直到解決。

範例

請在你的伺服器上替換佔位符。API Key 不能出現在公開的瀏覽器程式碼中。

curl --request POST \
  --url https://removezero.com/api/v1/remove-background \
  --header 'Authorization: Bearer rz_live_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-08-25-0001' \
  --data '{"input":{"image_base64":"BASE64_IMAGE_DATA","output":{"format":"webp","background":"#ffffff","width":1600,"height":1600,"padding_ratio":0.08}}}'

常用輸出起點

以下配方只是起點，不構成任何平台或類目的永久合規保證。平台名稱只是標籤，不是 API 枚舉值。

{"format":"png","background":"transparent","width":1600,"height":1600,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1600,"height":2000,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1500,"height":2000,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":1920,"height":1080,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":2000,"height":2000,"padding_ratio":0.075}

{"format":"webp","background":"#ffffff","width":2048,"height":2048,"padding_ratio":0.08}

錯誤與排錯

錯誤響應包含穩定的 HTTP 狀態碼和簡短的 JSON 錯誤碼。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE"
  }
}

安全排錯

1. 記錄 HTTP 狀態碼、錯誤碼、存在時的 request_id、時間和 Idempotency-Key。
2. 不要記錄或傳送 Bearer Key、完整 image_base64 或包含圖片資料的完整響應。
3. 先修正 4xx 對應的請求、憑據、餘額或請求標頭問題。
4. 遵守 Retry-After；未解決請求繼續使用原始請求內容和 Key。
5. 狀態持續無法解決時，只向支援提供非敏感標識。

請求限制

每次請求傳送一張 JPG、PNG 或 WebP 圖片的標準 Base64。解碼輸入最多 5 MiB，完整 JSON 請求內容最多 7,500,000 位元組。自訂輸出每邊最多 4,096 像素且不超過 4,194,304 總像素。若精確尺寸或格式無法放入內聯響應，請求會失敗並返還保留點數；API 不會靜默改變尺寸或格式。