服装分割API

免费体验

对图片中的服装和人像区域进行语义分割，并按所选类别返回灰度 mask 结果。支持异步、同步两种调用方式，适合接入生产流程。

接口返回的结果链接有效期为 1 小时，请及时下载并存储。

鉴权

每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。

X-API-KEY: YOUR_API_KEY

创建服装分割任务

POST /api/tasks/visual/r-clothing-segmentation

请求参数

image_url string 可选

源图像 URL。与 image_file 二选一；如果传入此参数，其他图像源参数必须为空。

二选一必填
image_file file 可选

源图像文件（二进制 multipart）。与 image_url 二选一；如果传入此参数，其他图像源参数必须为空。

图片上传要求请参看使用规范与限制#4。

sync string | number 可选

是否等待结果就绪并立即返回。0 表示异步返回 task_id，稍后通过 task_id 获取结果；1 表示同步等待结果并立即返回。结果最多保留 1 小时。

detail_mode number 可选

分割细节模式。1 = 细粒度常规（默认）。2 = 细粒度极高。若不需要衣服全部细分灰度图，建议选择细粒度常规。

output_type number 可选

输出内容。1 = 仅返回同语义灰度图合并结果（默认）。2 = 仅返回同语义全部细分灰度图，指定语义的全部灰度图会打包成 ZIP，目前仅支持衣服。3 = 两者都返回。

quality number 可选

分割质量。1 表示常规分割质量（默认）；2 表示高精度质量。

class_type number 可选

返回的语义类别。1 = 仅服装部分：clothes, tops, bottoms, dress, acc（默认）。2 = 服饰部分：clothes, tops, bottoms, dress, bag, shoes, acc。3 = 人像部分：hair, face, head, body。4 = 全部返回：hair, face, head, clothes, tops, bottoms, dress, bag, shoes, acc, body, others。
hair 头发，face 脸，head 头，clothes 衣服，shoes 鞋子，bag 包，acc 饰品，tops 上装，bottoms 下装，dress 连衣裙，body 肢体，others 其他。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见 状态码说明。

message string

接口返回消息。成功时通常为 success。

data.task_id string

异步服装分割任务 ID。创建任务成功后返回，用于后续查询服装分割结果。

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见 状态码说明。

message string

接口返回消息。成功时通常为 success。

data.task_id string

服装分割任务 ID。

data.created_at string

任务创建时间，Unix 时间戳字符串。

data.processed_at string

任务开始处理时间，Unix 时间戳字符串。

data.completed_at string

任务完成时间，Unix 时间戳字符串。

data.clothes_masks string

细分服装灰度 mask ZIP 链接（返回时有效期为 1 小时）。

data.class_masks object

按语义类别返回的结果 mask URL 或 base64 数据，例如 acc、body、clothes、face、hair、others、shoes。

data.output_type number

返回结果类型。

data.progress number

任务处理进度。100 表示处理完成。

data.state number

任务状态码。1 表示处理成功，大于 1 表示处理中，小于 0 表示失败，详见 状态码说明。

查询服装分割结果

异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 120 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。

GET /api/tasks/visual/r-clothing-segmentation/{task_id}

路径参数

task_id string 必填

服装分割任务 ID。创建异步服装分割任务后返回，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见 状态码说明。

message string

接口返回消息。成功时通常为 success。

data.task_id string

服装分割任务 ID。

data.created_at string

任务创建时间，Unix 时间戳字符串。

data.processed_at string

任务开始处理时间，Unix 时间戳字符串。

data.completed_at string

任务完成时间，Unix 时间戳字符串。

data.clothes_masks string

细分服装灰度 mask ZIP 链接（返回时有效期为 1 小时）。

data.class_masks object

按语义类别返回的结果 mask URL 或 base64 数据，例如 acc、body、clothes、face、hair、others、shoes。

data.output_type number

返回结果类型。

data.progress number

任务处理进度。100 表示处理完成。

data.state number

任务状态码。1 表示处理成功，大于 1 表示处理中，小于 0 表示失败，详见 状态码说明。

使用规范与限制

  1. 接口返回的结果链接有效期为 1 小时，请及时下载并存储。

  2. HTTP status 为 200 仅表示 HTTP 请求成功，任务是否成功需结合 status 和 data.state 判断。

  3. URL 作为参数传递时请遵守 URL 编码规范，避免参数解析混乱。

  4. 上传图片需符合以下格式、分辨率和大小限制。

    格式分辨率大小
    jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw最大 4096x4096最大20MB