Skip to main content
阿里云百炼 home page阿里云百炼
创意工具

人物实例分割API参考

本文介绍人物实例分割模型的输入输出参数。人物实例分割运用了检测和分割技术，不仅能够在图像中识别出不同的对象，而且还能准确地画出每一个对象边界的像素级掩码（mask）。

相关指南：人物实例分割
  • 本文档仅适用于华北2（北京）地域，且必须使用该地域的API Key。
  • image-instance-segmentation 模型当前仅提供免费体验，免费额度用完后不可调用且不支持付费。

模型概览

模型名免费额度（查看）计费单价限流（含主账号与RAM子账号）
任务下发接口QPS限制同时处理中任务数量
image-instance-segmentation500张目前仅供免费体验。
免费额度用完后不可调用，敬请关注后续动态。
21

前提条件

您需要已获取与配置 API Key并配置API Key到环境变量。请将示例代码中的 DASHSCOPE_API_HOST 替换为获取的 API Host。

HTTP调用

为了减少等待时间并且避免请求超时，服务采用异步方式提供。您需要发起两个请求：
  • 创建任务：首先发送一个请求创建人物实例分割任务，该请求会返回任务ID。
  • 根据任务ID查询结果：使用上一步获得的任务ID，查询模型生成的结果。

步骤1：创建任务获取任务ID

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis 调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求头（Headers）

Content-Typestring必选请求内容类型。固定为application/json。Authorizationstring必选推荐您使用阿里云百炼API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。X-DashScope-Asyncstring必选是否开启异步处理。必须开启异步处理，设置为enable。

请求体（Request Body）

modelstring必选调用模型。inputobject必选输入图像的基本信息，比如图像URL。

属性

image_urlstring必选输入图像URL地址。URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。图像限制：
  • 图片格式：JPEG，PNG，JPG，BMP，WEBP。
  • 图像分辨率：不低于512×512像素且不超过4096×4096像素。
  • 图像单边长度范围：[512, 4096]，单位像素。
  • 图片大小：不超过10M。
  • URL地址中不能包含中文字符。
  • 人物实例分割
# 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
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":{
    }
}'

响应

outputobject任务输出信息。

属性

task_idstring任务id，任务唯一标识。task_statusstring任务状态。
  • PENDING：排队中
  • RUNNING：处理中
  • SUSPENDED：挂起
  • SUCCEEDED：执行成功
  • FAILED：执行失败
codestring接口错误码。接口成功请求不会返回该参数。messagestring接口错误信息。接口成功请求不会返回该参数。request_id（可选）string本次请求的系统唯一码。
{
    "output": {
        "task_status": "PENDING",
        "task_id": "53950fb7-281a-4e60-xxxxxxxxxxxx"
    },
    "request_id": "1027557e-8c3f-9db5-8cd2-xxxxxxxxxxxx"
}

步骤2：根据任务ID查询结果

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} 调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求头（Headers）

Authorizationstring必选API-Key，例如：Bearer d1**2a。

URL路径参数（Path parameters）

task_idstring必选任务id。
  • 获取任务结果
# 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/53950fb7-281a-4e60-xxxxxxxxxxxx

响应

request_idstring本次请求的系统唯一码。status_codeint200（HTTPStatus.OK）表示请求成功，否则表示请求失败，可以通过code获取错误码，通过message字段获取错误详细信息。codestring如果失败表示错误码，参考错误码表。messagestring如果失败，内容为失败详细信息。outputobject任务输出信息。

属性

task_idstring任务id。task_statusstring任务状态。
  • PENDING：排队中。
  • RUNNING：处理中。
  • SUCCEEDED：成功。
  • FAILED：失败。
  • UNKNOWN：任务不存在或状态未知。
output_image_urlstring分割后图像URL地址。限制输出图像长宽比范围为1:10-10:1。output_vis_image_urlstring分割后可视化图像的URL地址，限制输出图像长宽比范围为1:10-10:1。
usageobject输出信息统计。

属性

image_countinteger本次请求生成图像数量。
  • 任务执行成功
  • 任务执行中
  • 任务执行失败
对于本模型，任务在结束之后的状态会持续保留24小时以备客户随时查询，24小时之后，任务将从系统中清除，相关的结果也将一并清除；对应的，任务生成的结果为图像的URL地址，出于安全考虑，该URL的下载有效期也是24小时，需要用户在获取任务结果后根据需要及时使用或者转存。
{
    "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
    }
}

补充：如何从人物实例分割掩码图中获取保留人物和待擦除人物掩码图？

以下代码示例将得到的人物实例分割结果图拆分成擦除区域图以及保留区域图，后续调用图像擦除模型擦除不需要的人像。

原图

人物实例分割结果

保留区域

擦除区域

图片擦除2-原图.png

image

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])

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。 此API还有特定状态码，具体如下所示。

HTTP状态码

接口错误码（code）

接口错误信息（message）

含义说明

400

InvalidParameter.JsonPhrase

input json error

输入JSON错误

400

InvalidParameter.FileDownload

oss download error

输入图像下载失败

400

InvalidParameter.ImageFormat

read image error

读取图像失败

400

InvalidParameter.ImageContent

The image content does not comply with green network verification.

图像内容不合规

400

InvalidParameter

the parameters must conform to the specification: xxx

输入参数超出范围

500

InternalError.Algo

algorithm process error

算法错误

500

InternalError.FileUpload

oss upload error

文件上传失败

阿里云百炼 home page阿里云百炼
使用 API
文本生成
图像生成
视频生成
3D模型生成
音频
实时多模态
Realtime API
  • 概述
向量与排序
更多模型
工具包/框架
模型生产
文件管理
更多