服装分割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 可选

是否等待结果就绪并立即返回。 结果最多保留 1 小时。

  • 0：异步返回 task_id，稍后通过 task_id 获取结果；
  • 1：同步等待结果并立即返回。
detail_mode number 可选

分割细节模式。 默认值为 1。若不需要衣服全部细分灰度图，建议选择细粒度常规。

  • 1：细粒度常规；
  • 2：细粒度极高。
output_type number 可选

输出内容。 默认值为 1。

  • 1：仅返回同语义灰度图合并结果；
  • 2：仅返回同语义全部细分灰度图，指定语义的全部灰度图会打包为 ZIP，目前仅支持衣服；
  • 3：两者都返回。
quality number 可选

分割质量。 默认值为 1。

  • 1：常规分割质量；
  • 2：高精度质量。
class_type number 可选

返回的语义类别。 默认值为 1。hair 为头发，face 为脸，head 为头，clothes 为衣服，shoes 为鞋子，bag 为包，acc 为饰品，tops 为上装，bottoms 为下装，dress 为连衣裙，body 为肢体，others 为其他。

  • 1：仅服装部分，包括 clothes、tops、bottoms、dress、acc；
  • 2：服饰部分，包括 clothes、tops、bottoms、dress、bag、shoes、acc；
  • 3：人像部分，包括 hair、face、head、body；
  • 4：返回全部类别。

返回参数

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