Background Removal API Documentation

Description

This cloud API uses intelligent salient object detection (SOD) for automated, high-precision background removal. Keep source images under 5 MB for optimal speed.

🥥 Important Notes

Data Retention: Output image URLs and alpha mattes (masks) are valid for 1 day only. Download and store them promptly.
Rate Limits: The default limit is 2 QPS. Contact sales or business development for higher concurrency.

Version History

4.0 | Release Date: 2025-03-20
4.0.1 | Release Date: 2026-07-01 (Added support for multi-result outputs)

Input Image Requirements

Image Format	Resolution	File Size
jpg, jpeg, bmp, png, webp, bitmap, avif, tiff, heic, heif	Integer between [4096~4096]	Up to 10MB (inclusive)

🥥 Important Notes

Output URLs expire after 24 hours.
Default rate limit is 2 QPS. Contact us to upgrade concurrency limits.

Request URL

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

Request Methods & Examples

# Create Task

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'

# Fetch Task

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}'

Authentication & Permissions

Request an API Key before using these services. Contact business development or sales for details.
API Authentication: Pass your secret token via the HTTP Header and store your API Key securely.

Construct Request

1、Image Background Removal

POST /api/v1/segment/submit

Request Parameters:

Parameter Name	Type	Default Value	Optional Values	Description
image_url	String	None	-	URL of the image to remove the background from (mutually exclusive with image_file).
image_file	String($binary)	None	-	Local image file (mutually exclusive with image_url).
rsz_w	int	None	Integer between [0~4096]	If greater than 0, scale the returned image proportionally to rsz_w.
rsz_h	int	None	Integer between [0~4096]	If greater than 0, scale the returned image proportionally to rsz_h.
crop_object	int	None	0、1	Set to 1 to crop to the main subject area.
multi_result	int	None	0、1	Whether to return multiple matting results. Billing is based on returned result count, normally no more than 5.
sync	int	0	0、1	0 returns task_id immediately for later task_info polling; 1 waits for completion and returns the result.
output_type	int	1	1、2、3	Return image and mask results. 1 Image only. 2 Image and mask. 3 Mask only.
output_format	String	png	jpeg、png	Returned image format. png: transparent background. jpeg: white background by default; use bg_color for another color.
bg_color	String	None	Hexadecimal color string starting with "#"	Solid background color, effective only when output_format is jpeg. Examples: "#FFFFFF", "#000000".
output_mask_format	String	jpeg	jpeg、png	Returned mask image format.
timeout	int	10	1-60	API processing wait timeout in seconds, effective only when sync=1.

Note: Setting both rsz_w and rsz_h scales to those dimensions without preserving aspect ratio. crop_object also does not preserve the original aspect ratio.

# Example Response for Async Mode (sync=0)

JSON|

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

# Example Response for Sync Mode (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、Image Background Removal

POST /api/v1/segment/submit

Request Parameters:

# Example Response for Async Mode (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"
}

Parameter Name	Type	Description
result_cnt	Number	Number of results returned when multi_result=1

Parameter Name	Type	Default Value	Optional Values	Description
task_id	String	None	Valid Task ID	task_id returned by the background removal API, for async mode with sync=0.

3、Usage Quota Inquiry

GET /api/v1/segment/quota

Request Parameters: None

# Example Response

Plain Text|

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

Response Parameters

Parameter Name	Type	Description
image	String	URL of the image after background removal
mask	String($binary)	URL of the mask image
results	Array	Result array when multi_result=1
result_cnt	Number	Number of results returned when multi_result=1
status	String	data.status task status: 2 Completed 1 Processing -1 Failed -2 Timed out
used_tasks	Number	Number of matting tasks used
remaining_tasks	Number	Number of remaining available matting tasks

Status Codes

HTTP Response Status Codes

HTTP Response Status Code	Description
200	Request successful.
400	Client parameter error. Check missing or invalid values.
401	Authentication failed. Check X-API-KEY and service activation.
404	Requested URL or resource does not exist.
412	Uploaded image URL or file validation failed.
413	Uploaded file exceeds the size limit.
429	Request frequency exceeds the QPS limit. Slow down or contact business support.
500	Server exception. Contact business or technical support.