背景移除 API 文件

說明

此雲端 API 使用智慧顯著目標檢測（SOD），提供自動化、高精度的背景移除服務。為獲得最佳速度，建議源圖片小於 5 MB。

🥥 重要說明

資料保留：輸產出圖片片 URL 和 Alpha 遮色片僅保留 1 天，請及時下載儲存。
頻率限制：預設限制為 2 QPS。如需更高併發，請聯絡銷售或商務團隊。

版本歷史

4.0 | 釋出日期: 2025-03-20
4.0.1 | 釋出日期: 2026-07-01 (新增多結果輸出支援)

輸入圖片要求

圖片格式	解析度	檔案大小
jpg, jpeg, bmp, png, webp, bitmap, avif, tiff, heic, heif	Integer between [4096~4096]	不超過 10MB（含）

🥥 重要說明

輸出 URL 將在 24 小時後過期。
預設限制為 2 QPS。如需提高併發限制，請聯絡我們。

請求 URL

🥥 https://coco-openapi.yezisheji.com/api/v1/segment/submit
https://coco-openapi.yezisheji.com/api/v1/segment/task_info

請求方法與示例

# 建立任務

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/submit' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_file=@/path/of/image.jpg'

# 查詢任務

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/task_info' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'task_id={YOUR_TASK_ID}'

鑑權與許可權

使用服務前需申請 API Key，取得方式請聯絡商務或銷售團隊。
API 鑑權：透過 HTTP Header 傳遞金鑰，請安全儲存 API Key，防止憑據洩露。

構造請求

1、圖片背景移除

POST /api/v1/segment/submit

請求引數:

引數名	型別	預設值	可選值	說明
image_url	String	None	-	需要移除背景的圖片 URL（與 image_file 互斥）。
image_file	String($binary)	None	-	本地圖片檔案（與 image_url 互斥）。
rsz_w	int	None	Integer between [0~4096]	大於 0 時，按 rsz_w 指定寬度等比縮放返回圖片。
rsz_h	int	None	Integer between [0~4096]	大於 0 時，按 rsz_h 指定高度等比縮放返回圖片。
crop_object	int	None	0、1	設為 1 時，裁切到圖片主體區域。
multi_result	int	None	0、1	是否返回多個去背結果。按返回結果數量計費，通常不超過 5 個。
sync	int	0	0、1	0 為非同步模式，立即返回 task_id 並透過 task_info 查詢；1 等待完成後返回結果。
output_type	int	1	1、2、3	返回圖片與遮色片。 1 僅返回圖片。 2 返回圖片和遮色片。 3 僅返回遮色片。
output_format	String	png	jpeg、png	返回圖片格式。 png：透明背景。 jpeg：預設白色背景，可用 bg_color 指定顏色。
bg_color	String	None	Hexadecimal color string starting with "#"	純色背景，僅在 output_format 為 jpeg 時生效，例如 "#FFFFFF"、"#000000"。
output_mask_format	String	jpeg	jpeg、png	返回遮色片圖片的格式。
timeout	int	10	1-60	API 等待處理的超時時間（秒），僅在 sync=1 時生效。

注意：同時設定 rsz_w 和 rsz_h 時，將按指定尺寸縮放且不保持原寬高比；啟用 crop_object 時也不會保持原寬高比。

# 非同步模式響應示例 (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcadf7b3b99f4447f9ddce"
    },
    "status": 200,
    "timestamp": 1744512855,
    "trace_id": "ae173819-6fb5-4e88-a587-ff654f2de9bf",
    "message": "ok"
}

# 同步模式響應示例 (sync=1)

JSON|

{
    "data": {
        "created_at": 1744513021,
        "completed_at": 1744513022,
        "image": "{image oss url}",
        "mask": "{mask oss url}"
    },
    "status": 200,
    "timestamp": 1744513022,
    "trace_id": "3a2a0b4a-8b4a-4034-865a-8a5ebcc7e93c",
    "message": "ok"
}

2、圖片背景移除

POST /api/v1/segment/submit

請求引數:

# 非同步模式響應示例 (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcaec66b4a4af9c824fcd2",
        "created_at": 1744513062,
        "completed_at": 1744513063,
        "status": 2,
        "mask": "{mask oss url}",
        "image": "{image oss url}",
        "result_cnt": 2,
        "results": [
            {
                "task_id": "{task_id_1}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            },
            {
                "task_id": "{task_id_2}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            }
        ]
    },
    "status": 200,
    "timestamp": 1744513180,
    "trace_id": "952a636e-3a9d-4e72-b470-681c61fcd763",
    "message": "ok"
}

引數名	型別	說明
result_cnt	Number	multi_result=1 時返回的結果數量

引數名	型別	預設值	可選值	說明
task_id	String	None	Valid Task ID	背景移除 API 返回的 task_id，僅用於 sync=0 非同步模式。

3、用量配額查詢

GET /api/v1/segment/quota

請求引數: 無

# 響應示例

Plain Text|

{
    "data": {
        "used_tasks": 888,
        "remaining_tasks": 88888
    },
    "status": 200,
    "timestamp": 1778555905,
    "trace_id": "b9d83cd6-f220-436f-ac30-52fcd8d5b30a",
    "message": "ok"
}

響應引數

引數名	型別	說明
image	String	背景移除後圖片的 URL
mask	String($binary)	遮色片圖片 URL
results	Array	multi_result=1 時的結果陣列
result_cnt	Number	multi_result=1 時返回的結果數量
status	String	data.status 任務狀態： 2 已完成 1 處理中 -1 失敗 -2 超時
used_tasks	Number	已使用的去背任務數量
remaining_tasks	Number	剩餘可用去背任務數量

狀態碼

HTTP 響應狀態碼

HTTP 響應狀態碼	說明
200	請求成功。
400	客戶端引數錯誤，請檢查缺失或無效值。
401	鑑權失敗，請檢查 X-API-KEY 和服務開通狀態。
404	請求的 URL 或資源不存在。
412	上傳的圖片 URL 或檔案校驗失敗。
413	上傳檔案超過大小限制。
429	請求頻率超過 QPS 限制，請降低頻率或聯絡商務支援。
500	伺服器異常，請聯絡商務或技術支援。