bgCut.net API

只需一個 HTTPS 請求,即可在您的應用程式、商店或處理流程中去除背景。

基礎 URL: https://bgcut.net/api/v1 · 取得金鑰請前往 API 金鑰.

驗證

每個請求都必須在 X-Api-Key 標頭中附上您的 API 金鑰。金鑰可在您的帳戶中建立及撤銷;每把金鑰皆可命名,方便您依應用程式分別輪替。

X-Api-Key: bgc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

或者,您也可以將其作為 Bearer 權杖傳送: Authorization: Bearer bgc_…

POST /remove

您可以透過 multipart 檔案、URL 或 base64 編碼的方式傳送圖片。預設回應為處理後的圖片(二進位)。

參數

參數類型說明
image_filefile圖片檔案(multipart/form-data)。支援 JPG、PNG、WebP、GIF、BMP、TIFF;上限 25 MB / 3000 萬像素。
image_urlstring要擷取的圖片公開 URL,可取代上傳。
image_file_b64stringBase64 編碼的圖片(可加上 data: 前綴)。
sizeauto | preview | fullpreview = 最大 640 px(使用每月免費額度,不扣點數);full = 原始解析度(1 點);auto(預設)= 有點數時使用 full,否則使用 preview。
formatpng | jpg | webp輸出格式。png 保留透明度;jpg 會以 bg_color 填滿背景(預設為白色)。
modelfast | hq | portraitlite(預設,約 6 秒,最佳平衡)、fast(約 0.5 秒,預覽品質)、hq(約 15 秒,最高品質)、portrait(約 0.3 秒,僅限人像)。
bg_colorstring背景的十六進位色碼,例如 #ffffff。省略則為透明背景。
bg_blurnumber保留原始背景,並以此半徑(像素,1–200)進行模糊,例如設為 25 可呈現人像模式效果。此設定會覆寫 bg_color。
cropboolean將輸出裁切至主體的邊界框。
crop_margininteger裁切時在主體周圍額外保留的邊距(像素,0–200)。
roistring以比例 x,y,w,h(0–1)表示的感興趣區域。AI 只會分析此矩形內的內容,矩形外的區域一律變為透明。
feathernumber以此半徑(像素,0–5)柔化邊緣。
qualityintegerJPG/WebP 品質 50–100(預設 92)。
responsebinary | jsonbinary(預設)回傳圖片;json 回傳中繼資料及 base64 圖片。

回應

請求成功時會回傳 HTTP 200、圖片位元組及下列標頭:

HTTP/1.1 200 OK
Content-Type: image/png
X-Credits-Charged: 1
X-Credits-Remaining: 149
X-Free-Remaining: 5
X-Width: 3000
X-Height: 2000
X-Image-Id: 1f3a…
X-Type: hd

使用 response=json 時,您會收到:

{
  "ok": true,
  "image": { "id": "1f3a…", "width": 3000, "height": 2000, "format": "png", "type": "hd", "bytes": 812345, "bbox": [120, 40, 2810, 1990], "data": "iVBORw0KGgo…" },
  "credits_charged": 1,
  "credits_remaining": 149,
  "free_remaining": 5
}

GET /account

curl https://bgcut.net/api/v1/account -H "X-Api-Key: bgc_…"

{ "ok": true, "email": "[email protected]", "credits": 149, "free_remaining": 5, "free_per_month": 5, "free_max_width": 640, "rate_limit_per_minute": 60 }

GET /images

回傳以您的 API 金鑰處理的最近 100 張圖片,並附上編輯器 URL,方便您在瀏覽器中進一步調整。

錯誤

錯誤以 JSON 格式回傳,包含錯誤代碼及易讀的訊息:

{ "ok": false, "error": "insufficient_credits", "message": "No credits left. Buy credits at https://bgcut.net/pricing or request size=preview." }
HTTPerror說明
400bad_request / missing_image缺少參數或參數無效。
401auth_required / invalid_keyAPI 金鑰缺少、無效或已撤銷。
402insufficient_credits / free_quota_exceeded點數不足(完整尺寸)或免費額度已用完(預覽)。
422too_large / bad_type / fetch_failed無法讀取或下載圖片。
429rate_limited請求次數過多,請放慢速度,或聯絡我們以提高限制。
500processing_failed我們這端處理失敗,您不會被收費。

範例程式碼

所有範例皆使用相同的端點。下載完整範例集: bgcut-api-examples.zip

官方 PHP SDK
開源用戶端函式庫,提供型別化的結果、錯誤類別及可直接執行的範例。採用 MIT 授權。
composer require bgcut-net/bgcut-php
GitHub

限制

  • 每把 API 金鑰每分鐘 60 個請求(可申請提高限制)。
  • 每張圖片上限 25 MB 及 3000 萬像素;超過的圖片會自動縮小。
  • 處理後的圖片會保留 30 天,並可在網頁編輯器中進一步調整。
  • 失敗的請求一律不收費;若輸出產生失敗,已扣除的費用會自動退還。

開始整合

建立免費帳戶、產生金鑰,不到一分鐘即可完成第一次呼叫。

取得 API 金鑰 價格方案