Human instance segmentation API reference

This topic describes the input and output parameters of the person instance segmentation model. Person instance segmentation is a technique that detects different objects in an image and generates a precise, pixel-level mask to define the border of each object instance.

Related guide: Human instance segmentation

Model overview

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.

# 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":{
    }
}'

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

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-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.

# 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

{
    "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.

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.