Human instance segmentation API reference

Related guide: Human instance segmentation

This document applies only to the China (Beijing) region. You must use an API key from this region.
The image-instance-segmentation model is currently available for a free trial only. After the free quota is used up, you can no longer call the model. Paid usage is not supported.

Model overview

Model name	Free quota(View)	Billing unit price	Throttling (including Alibaba Cloud accounts and RAM users)
			QPS limit for the task submission API	Number of tasks in simultaneous processing
image-instance-segmentation	500 images	For free trial only. You cannot make calls after the free quota is used up. Please stay tuned for future updates.	2	1

Prerequisites

Obtain an API key and export the API key as an environment variable.

HTTP call

To reduce waiting times and avoid request timeouts, this service is provided in asynchronous mode. You must make two requests:

Create a task: First, send a request to create a human instance segmentation task. This request returns a task ID.
Query the result using the task ID: Use the task ID that you retrieved in the previous step to query the result generated by the model.

Step 1: Create a task to obtain a task ID

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis Replace {WorkspaceId} with your actual workspace ID.

Request headers

Content-Type string RequiredThe content type of the request. The value must be application/json.Authorization string RequiredUse your Alibaba Cloud Model Studio API key. You can also use a DashScope API key. For example, Bearer d1xxx2a.X-DashScope-Async string RequiredSpecifies whether to enable asynchronous processing. Set this parameter to enable.

Request body

model string RequiredThe model to call.input object RequiredThe basic information of the input image, such as the image URL.

Property

image_url string RequiredThe URL of the input image.The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.Image limits:

Image format: JPEG, PNG, JPG, BMP, or WEBP.
Image resolution: from 512 × 512 pixels to 4096 × 4096 pixels.
The length of each side of the image must be between 512 and 4,096 pixels.
Image size: no more than 10 MB.
The URL cannot contain Chinese characters.

Human instance segmentation

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location --request POST 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "image-instance-segmentation",
    "input": {
            "image_url": "http://xxx/image.png"
        },
    "parameters":{
    }
}'

Response

output objectThe output information of the task.

Property

task_id stringThe unique ID of the task.task_status stringThe status of the task.

PENDING: The task is in the queue.
RUNNING: The task is in progress.
SUSPENDED: The task is suspended.
SUCCEEDED: The task completed successfully.
FAILED: The task failed.

code stringThe error code for the API call. This parameter is not returned if the request is successful.message stringThe error message for the API call. This parameter is not returned if the request is successful.request_id string (Optional)The unique ID for this request.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "53950fb7-281a-4e60-xxxxxxxxxxxx"
    },
    "request_id": "1027557e-8c3f-9db5-8cd2-xxxxxxxxxxxx"
}

Step 2: Query the result based on the task ID

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} Replace {WorkspaceId} with your actual workspace ID.

Request headers

Authorization string RequiredThe API key. Example: Bearer d1**2a.

URL path parameters

task_id string RequiredThe task ID.

Obtain task result

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/53950fb7-281a-4e60-xxxxxxxxxxxx

Response

request_id stringThe unique ID for this request.status_code intA value of 200 (HTTPStatus.OK) indicates that the request is successful. Other values indicate that the request failed. If the request fails, you can retrieve the error code from the code field and the error details from the message field.code stringIf an error code is returned, see the error code table.message stringIf an operation fails, the content includes failure details.output objectThe output information of the task.

Property

task_id stringThe task ID.task_status stringThe status of the task.

PENDING: The task is in the queue.
RUNNING: The task is in progress.
SUCCEEDED: The task is successful.
FAILED: The task failed.
UNKNOWN: The task does not exist or its status is unknown.

output_image_url stringThe URL of the segmented image. The aspect ratio of the output image must be between 1:10 and 10:1.output_vis_image_url stringThe URL of the visualized segmented image. The aspect ratio of the output image must be between 1:10 and 10:1.

usage objectOutput statistics.

Property

image_count integerThe number of images generated for this request.

Task executed successfully
Task in progress
Task failed

For this model, the status of a completed task is retained for 24 hours, during which you can query it at any time. After 24 hours, the task and its results are deleted from the system. The task result is an image URL. For security reasons, the URL is valid for only 24 hours. After you retrieve the task result, you must use or save the image.

{
    "request_id": "b67df059-ca6a-9d51-afcd-9b3c4456b1e2",
    "output": {
        "task_id": "53950fb7-281a-4e60-xxxxxxxxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2024-05-16 13:50:01.247",
        "scheduled_time": "2024-05-16 13:50:01.354",
        "end_time": "2024-05-16 13:50:27.795",
        "output_image_url": "http://xxx/result1.png",
        "output_vis_image_url":"http://xxx/result2.png"
    },
    "usage": {
        "image_count": 1
    }
}

{
    "request_id":"7574ee8f-38a3-4b1e-xxxxxxxxxxxx",
    "output":{
        "task_id":"53950fb7-281a-4e60-xxxxxxxxxxxx",
        "task_status":"RUNNING",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

{
    "request_id": "dccfdf23-b38e-97a6-a07b-f35118c1ada6",
    "output": {
        "task_id": "53950fb7-281a-4e60-xxxxxxxxxxxx",
        "task_status": "FAILED",
        "submit_time": "2024-05-16 14:15:14.103",
        "scheduled_time": "2024-05-16 14:15:14.154",
        "end_time": "2024-05-16 14:15:14.694",
        "code": "InvalidParameter.FileDownload",
        "message": "download for input_image error"
    }
}

Appendix: How to separate masks for preserved and erased people

The following code example shows how to split the resulting human instance segmentation image into an reserved area image and a removed area image. You can then call an image erasing model to remove the unwanted person.

Original image	Human instance segmentation result	Reserved area	Removed area
	mask.png	reserve.png	remove.png

Original image

Human instance segmentation result

Reserved area

Removed area

图片擦除2-原图.png

mask.png

图片擦除2-保留.png

reserve.png

图片擦除2-擦除.png

remove.png

import cv2
import numpy as np

def get_remove_mask(mask_path, remove_mask_path, reserve_ids=[]):
    mask = cv2.imread(mask_path)
    instance_num = int(mask.max())
    new_mask = np.zeros((mask.shape[0], mask.shape[1], 3))
    for i in range(1, instance_num+1):
        if i in reserve_ids:
            continue
        new_mask[mask[:, :, 0] == i] = (255, 255, 255)
    cv2.imwrite(remove_mask_path, new_mask.astype(np.uint8))

def get_reserve_mask(mask_path, reserve_mask_path, reserve_ids=[]):
    mask = cv2.imread(mask_path)
    instance_num = int(mask.max())
    new_mask = np.zeros((mask.shape[0], mask.shape[1], 3))
    for i in range(1, instance_num + 1):
        if i in reserve_ids:
            new_mask[mask[:,:,0] == i]  = (255, 255, 255)
    cv2.imwrite(reserve_mask_path, new_mask.astype(np.uint8))

if __name__ == '__main__':
    mask_path = 'mask.png'
    remove_mask_path = 'remove.png'
    reserve_mask_path = 'reserve.png'
    get_remove_mask(mask_path, remove_mask_path, reserve_ids=[1])
    get_reserve_mask(mask_path, reserve_mask_path, reserve_ids=[1])

Error codes

If the model call fails and returns an error message, see Error codes for resolution. This API also has the following specific status codes.

HTTP status code	Error code (code)	Error message (message)	Description
400	InvalidParameter.JsonPhrase	input json error	Invalid JSON input.
400	InvalidParameter.FileDownload	oss download error	Failed to download the input image.
400	InvalidParameter.ImageFormat	read image error	Failed to read the image.
400	InvalidParameter.ImageContent	The image content does not comply with green network verification.	The image content is not compliant.
400	InvalidParameter	the parameters must conform to the specification: xxx	An input parameter is out of range.
500	InternalError.Algo	algorithm process error	An algorithm error occurred.
500	InternalError.FileUpload	oss upload error	The file failed to upload.

​Model overview

​Prerequisites

​HTTP call

​Step 1: Create a task to obtain a task ID

Request headers

Request body

Response

​Step 2: Query the result based on the task ID

Request headers

URL path parameters

Response

​Appendix: How to separate masks for preserved and erased people

​Error codes

Model overview

Prerequisites

HTTP call

Step 1: Create a task to obtain a task ID

Step 2: Query the result based on the task ID

Appendix: How to separate masks for preserved and erased people

Error codes