電商研發如何串接 Cutout.pro REST API 實現批次商品去背與圖片規格化

在海量商品批次上架的電商營運場景中，獨立站品牌與跨境多平台賣家團隊常常面臨嚴峻的圖片後製瓶頸：各級供應商交付的商品原始圖檔規格混亂，背景複雜、長寬比例各異且光影參差不齊。傳統的桌面端批次修圖工具雖然功能豐富，但無法與企業內部的 ERP、PIM（商品資訊管理系統）或 CMS 實現自動化工程整合；而依賴人工美工逐張修圖則會造成 24 至 72 小時的上架延遲，大幅推高單一 SKU 的人力營運成本。

Cutout.pro 提供了針對工業化視覺處理的開發者 REST API，具備商品去背、主體裁切與底色替換等核心能力。透過將該 API 整合進電商後端的非同步工作管線，工程團隊能將上架修圖環節縮短至數秒內，批次輸出符合 Amazon、Shopify 等平台規範的純白底（#FFFFFF）、統一邊距與自然接地陰影的標準商品圖。

一、Cutout.pro API 串接規範與鑑權流程

Cutout.pro 的所有開放能力均基於標準 HTTPS 協定。開發者發出請求時，必須在 HTTP 標頭中帶入專屬憑證：

APIKEY: your_cutout_pro_api_key_here

生產環境前置額度監測

在電商大促或換季鋪貨期間，單一批次常涵蓋數萬張商品圖片。若批次處理途中額度耗盡，會導致後續任務大量拋出 4001（餘額不足）例外而中斷。因此，管線應在啟動批次作業前主動預檢帳戶餘額。

Cutout.pro 提供了專屬的訂閱與餘額查詢端點：

• 請求端點： GET https://www.cutout.pro/api/v1/mySubscription
• 請求標頭： APIKEY: <YOUR_API_KEY>，Accept: application/json

成功回應將傳回帳戶的即時點數狀態：

{
  "code": 0,
  "data": {
    "monthBalance": 1250,
    "imageBalance": 5000,
    "videoBalance": 0,
    "monthStartDate": "2026-10-01 00:00:00",
    "monthExpireDate": "2026-11-01 00:00:00"
  },
  "msg": null,
  "time": 1728729600000
}

在排程引擎中加入配額預檢邏輯，能在點數不足時提早暫停任務並觸發警報，確保批量管線穩定運行。

二、端點模式選型與關鍵參數配置

針對電商商品與物件去背，Cutout.pro 建議指定 mattingType=6（通用去背，專用於商品、物件與動植物）或 mattingType=1。平台根據原始圖片儲存位置與系統資料傳輸格式提供了三種調用模式：

電商規格化核心請求參數

在發起去背請求時，合理配置以下參數可大幅簡化後續處理：

• mattingType（整數，必填）：電商商品去背固定設為 6。
• crop（布林值，選填）：設為 true 時，演算法會自動裁切掉周圍的透明空白，緊貼商品外輪廓完成邊界裁剪。
• cropMargin（字串，選填）：僅在 crop=true 時生效。可設定絕對像素（如 "30px"）或相對比例（如 "10%"），支援單值、雙值或四邊獨立邊距。
• bgcolor（十六進位字串，選填）：指定背景純色填充（如純白 FFFFFF，請勿加上 #）。若傳入特殊值 'blur' 則會產生背景模糊效果。
• outputFormat（字串，選填）：支援 png、webp 或 jpg_<品質>（例如 jpg_85）。
• preview（布林值，選填）：設為 true 時，輸出圖片解析度上限為 500x500 像素，每次成功調用僅扣除 0.25 點（未傳遞或為 false 則扣除 1 點，支援最高 4096x4096 像素與 15MB 檔案大小）。非常適合賣家端商品草稿的低成本預覽。

三、高並發非同步批次處理與限流佇列架構

Cutout.pro 的 HTTP API 屬於同步阻塞式調用：客戶端發送請求後，伺服器完成演算法運算並直接回傳結果。但官方對標準 API 設定了嚴格的速率上限：每秒並發請求數上限為 5 QPS。

若直接使用多執行緒全速並發調用，接口將頻繁拋出錯誤碼 5005（Too many requests in the queue, please wait）。因此，面向數萬級 SKU 的自動化管線必須透過非同步訊息佇列進行緩衝與解耦。

生產級微服務架構示意

[ERP / PIM 批次匯入]
        │ (推送 SKU 任務群組)
        ▼
[訊息中介軟體: Redis / RabbitMQ]
        │
        ▼
[Worker 消費叢集 (Celery / BullMQ)]
   ├── 權杖桶流控攔截器 (叢集嚴格限制 <= 4.5 QPS)
   ├── 調用 Cutout.pro API (POST /api/v1/matting?mattingType=6)
   │     └── 遇到 5005 時執行指數退避重試
   ├── 輕量圖形規格化引擎 (Pillow / Sharp)
   │     ├── 正方形畫布置中 (如 2000x2000)
   │     ├── 85% 黃金版面佔比縮放
   │     └── 生成真實接地接觸陰影 (Contact Shadow)
   ├── 物件儲存上傳 (AWS S3 / Cloudflare R2)
   └── Webhook 回呼 ERP 系統 (更新商品狀態與圖檔網址)

容錯與錯誤處理矩陣

1. 分散式權杖桶限流： 在任務消費層設定 Redis 權杖桶，確保叢集整體對外請求速率不超過 4.5 QPS，避免觸發服務端的 5005 拒絕機制。
2. 錯誤分類與自我修復策略：
   • 5005（排隊已滿 / 超頻）： 觸發指數退避機制（重試等待時間：1.5s、3s、6s，附帶微量隨機抖動）。
   • 1002（檔案超過 15MB）與 5008（格式無法辨識）： 將該 SKU 路由至死信佇列（DLQ），並在 ERP 營運後台標記「原始圖片需人工核對」。
   • 4001（點數耗盡）： 全域暫停消費佇列，並向維運與採購群組發送高危險警報。

四、圖片規格化全流程實踐：尺寸、邊距與陰影合成

雖然 API 原生支援以 bgcolor=FFFFFF 直接填補白底，但主流電商平台對首圖的要求更加嚴謹：

• 畫布必須為嚴格的正方形（如 1:1，2000x2000 像素）。
• 商品主體面積需佔據總畫布高度或寬度的 80% 至 85%，防止商品過大溢出或過小顯得空曠。
• 純白底直接貼圖容易產生突兀的「貼紙感」，需要配合商品底部輕微的接觸投影（Contact Shadow），還原商品陳列的立體感與份量感。

生產管線的最佳實踐是：向 Cutout.pro 請求透明切片（crop=true，不傳 bgcolor），隨後在本地 Worker 內部利用圖形庫進行尺寸標準化與陰影運算。

生產管線實作範例（Python + Pillow）

import io
import time
import requests
from PIL import Image, ImageFilter

CUTOUT_API_KEY = "YOUR_API_KEY_HERE"
API_URL = "https://www.cutout.pro/api/v1/matting?mattingType=6&crop=true"

def remove_background(image_bytes: bytes, max_retries: int = 3) -> bytes:
    """調用 Cutout.pro 接口，內建針對 5005 限流的指數退避機制"""
    headers = {"APIKEY": CUTOUT_API_KEY}
    files = {"file": ("product.jpg", image_bytes, "image/jpeg")}
    
    for attempt in range(max_retries):
        response = requests.post(API_URL, headers=headers, files=files, timeout=30)
        
        # 成功回傳二進位圖片
        if response.status_code == 200 and response.headers.get("Content-Type", "").startswith("image/"):
            return response.content
        
        # 解析異常 JSON
        try:
            err = response.json()
            code = err.get("code")
            msg = err.get("msg")
            
            if code == 5005:  # 並發佇列超限
                sleep_time = (2 ** attempt) + 0.5
                time.sleep(sleep_time)
                continue
            elif code == 4001:
                raise RuntimeError("Cutout.pro API 點數已耗盡")
            else:
                raise ValueError(f"Cutout.pro 處理失敗: {code} - {msg}")
        except requests.exceptions.JSONDecodeError:
            response.raise_for_status()

    raise TimeoutError("請求 Cutout.pro 重試次數超限")

def standardize_product_image(
    transparent_png_bytes: bytes,
    target_canvas_size: int = 2000,
    fill_ratio: float = 0.85
) -> Image.Image:
    """
    將圖片規格化至標準正方形純白畫布，適配 85% 視覺佔比，並合成自然接地陰影。
    """
    # 1. 載入商品透明切片
    product = Image.open(io.BytesIO(transparent_png_bytes)).convert("RGBA")
    prod_w, prod_h = product.size

    # 2. 等比例縮放至目標佔比 (fill_ratio)
    max_dimension = int(target_canvas_size * fill_ratio)
    scale = min(max_dimension / prod_w, max_dimension / prod_h)
    new_w, new_h = int(prod_w * scale), int(prod_h * scale)
    product_resized = product.resize((new_w, new_h), Image.Resampling.LANCZOS)

    # 3. 建立純白底正方形底板
    canvas = Image.new("RGBA", (target_canvas_size, target_canvas_size), (255, 255, 255, 255))

    # 4. 生成接地接觸陰影 (Contact Shadow)
    alpha = product_resized.split()[3]
    shadow_height = max(10, int(new_h * 0.08))
    
    # 縱向壓縮 Alpha 色版以模擬扁平著地區域
    shadow_mask = alpha.resize((new_w, shadow_height), Image.Resampling.BILINEAR)
    shadow_mask = shadow_mask.filter(ImageFilter.GaussianBlur(radius=15))
    
    # 建構半透明深灰色陰影圖層，不透明度限制在 35%
    shadow_layer = Image.new("RGBA", (new_w, shadow_height), (40, 40, 40, 0))
    shadow_layer.putalpha(shadow_mask.point(lambda p: int(p * 0.35)))

    # 5. 畫布圖層合成定位
    pos_x = (target_canvas_size - new_w) // 2
    pos_y = (target_canvas_size - new_h) // 2

    # 陰影位置微調至商品底部交界處
    shadow_y = pos_y + new_h - int(shadow_height * 0.6)
    canvas.paste(shadow_layer, (pos_x, shadow_y), shadow_layer)

    # 貼上商品主體前景
    canvas.paste(product_resized, (pos_x, pos_y), product_resized)

    # 輸出高畫質 RGB 影像
    return canvas.convert("RGB")

def run_sku_pipeline(raw_file_path: str, output_file_path: str):
    with open(raw_file_path, "rb") as f:
        raw_bytes = f.read()

    # 步驟一：雲端智慧去背
    cutout_bytes = remove_background(raw_bytes)

    # 步驟二：本地幾何規格化與陰影渲染
    standardized_img = standardize_product_image(cutout_bytes)

    # 步驟三：儲存最佳化後的主圖資產
    standardized_img.save(output_file_path, "JPEG", quality=90, optimize=True)

五、產線最佳實踐與成本控管建議

1. 善用 mattingByUrl 節省伺服器對外頻寬： 若原始圖片已存放於雲端物件儲存（如 S3 或 R2），建議優先採用 mattingByUrl 模式，直接傳入可公開存取的 URL。如此可免去應用伺服器重複下載與上傳的 I/O 開銷。
2. 兩階段畫質分流策略： 在賣家後台商品草稿審核階段，請求參數可帶入 preview=true，單張僅消耗 0.25 點數；待商品正式發佈上架時，再觸發全解析度去背（消耗 1 點數）。
3. 沉澱透明遮罩中間件： 建議將 Cutout.pro 回傳的透明 PNG 原版持久化至封存存儲。當平台營運策略微調（例如背景由純白改為淺灰，或邊距佔比重新調整）時，無需再次付費調用接口，只需於本地重跑合成腳本即可批次刷新商品圖。

參考資料

• Background Remover | Cutout Pro API documentation
• Error Code | Cutout Pro API documentation
• Price For API Call | Cutout Pro API documentation
• Fetch Credit Balance API | Cutout Pro API documentation
• API for Image Video AI processing - Cutout.Pro
• GitHub - cutout-pro/api-php-examples