Clothing Segmentation

Description

Identify clothing, accessories, and body-related regions in an image. The API returns a combined segmentation mask and individual class masks. Each class mask is identified by mask_label, allowing the corresponding region to be extracted.

Version

1.0

Image Requirements

  • Supported formats: JPG and PNG.
  • For image URLs, explicitly set media_data_type to url. Do not Base64-encode URLs.

Segmentation Classes

Class IDClass
0Background
1Headwear
2Hair
3Gloves
4Glasses
5Upper-body clothing
6Dress
7Outerwear
8Socks
9Trousers
10Skin
11Scarves and similar items
12Skirt
13Face
14Shoes
15Bags
16Accessories
17Jumpsuit
18Mannequin support post

The mask_label of an individual class mask is a string. For example, "0" means background and "6" means dress. The combined mask does not include mask_label.

Request URL

Task submission endpoint:

https://openapi.meitu.com/api/v1/sdk/sync/push
Task name (`task`): `/v1/clothing_segmentation/488136`
Task type (`task_type`): `formula`

HTTP Method

POST

Content-Type: application/json

Authentication

Use an AK/SK pair with access to this capability and sign requests with the signing SDK. See API Request Signing.

Request Parameters

RequiredParameterTypeDescription
YestaskstringFixed value: /v1/clothing_segmentation/488136.
Yestask_typestringFixed value: formula.
Yesinit_imagesarrayInput images. The examples provide one image for segmentation.
YesparamsstringA JSON-serialized string containing the algorithm parameters described below.
Nosync_timeoutintegerSynchronous waiting period in seconds. Default: 30.

init_images Element

RequiredParameterTypeDescription
YesurlstringImage URL or Base64-encoded data, matching profile.media_profiles.media_data_type.
YesprofileobjectImage properties.

profile

RequiredParameterTypeDescription
YesversionstringFixed value: v1.
Yesmedia_profilesobjectImage data type.
Nomedia_extraobjectAdditional image information. Omit when not needed.

media_profiles

RequiredParameterTypeDescription
Nomedia_data_typestringpng: Base64-encoded image data, with png specified as the default in the source parameter table; url: image URL. Explicitly set url for URL inputs.

params

params must be a string. Serialize the following object, assign the resulting string to params, and then serialize the entire request:

{
  "parameter": {
    "rsp_media_type": "base64"
  }
}
RequiredParameterTypeDescription
YesparameterobjectClothing segmentation parameters.
NoextraobjectAdditional processing information in the algorithm protocol. Omit when not needed.

parameter

RequiredParameterTypeDescription
Norsp_media_typestringbase64: return result images as Base64-encoded data. The source parameter table does not specify a default.

The source request example uses jpg for both media_data_type and rsp_media_type, contrary to its parameter tables. The requests here use URL input and base64 output as documented in those tables. jpg is not listed as a confirmed request value.

Request Example

Replace the image URL with an accessible URL for the image to segment.

{
  "task": "/v1/clothing_segmentation/488136",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://example.com/input.png",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "version": "v1"
      }
    }
  ],
  "params": "{\"parameter\":{\"rsp_media_type\":\"base64\"}}",
  "sync_timeout": 30
}

Response Fields

See Task Query for gateway task states and querying. Common gateway fields are listed below; the exact result nesting for this task has not been verified against a response sample.

FieldTypeDescription
codeintegerGateway business status code. 0 does not mean the algorithm task has completed; also check the task status.
messagestringGateway response message.
dataobjectTask information.
data.task_idstringGateway task ID used to query results.
data.statusintegerTask status; see below.
data.resultobjectTask result. The internal field nesting for this task remains unconfirmed.
data.statusDescription
-1Task not found.
0Task created.
1Running.
2Failed.
9Synchronous wait timed out. Continue querying; this does not indicate task failure.
10Succeeded.

Algorithm Result Fields

These fields come from the original direct algorithm endpoint. They are not documented here as root-level gateway response fields.

FieldTypeDescription
parameterobjectOutput type information.
parameter.rsp_media_typestringOutput data type. The source response field description and example both use jpg.
media_info_listarrayThe first element is the combined mask; subsequent elements are individual class masks.
media_info_list[].media_datastringMask image data. The source field description specifies Base64 data, while the success example labels it as url.
media_info_list[].media_profilesobjectMask image properties.
media_info_list[].media_profiles.media_data_typestringImage data type. The source field description specifies jpg, while the success example uses url.
media_info_list[].mask_labelstringClass ID for an individual mask; see Segmentation Classes. Absent for the combined mask.

Identify individual class masks by mask_label, not by their array indices. The source does not specify whether every class is returned in each response.

Algorithm Error Fields

FieldTypeDescription
ErrorCodeintegerAlgorithm error code.
ErrorMsgstringAlgorithm error message.
Datastring / nullAdditional information. The source error example uses null.

Response Examples

The examples below come from the original direct endpoint, with only JSON syntax corrected. ... represents omitted image data and cannot be used as-is. These are not live responses from this task or complete gateway responses. The inconsistency between rsp_media_type = jpg and media_data_type = url remains unconfirmed.

Algorithm Success Example

HTTP status in the source: 200.

{
  "parameter": {
    "rsp_media_type": "jpg"
  },
  "media_info_list": [
    {
      "media_data": "...",
      "media_profiles": {
        "media_data_type": "url"
      }
    },
    {
      "mask_label": "0",
      "media_data": "...",
      "media_profiles": {
        "media_data_type": "url"
      }
    },
    {
      "mask_label": "6",
      "media_data": "...",
      "media_profiles": {
        "media_data_type": "url"
      }
    }
  ]
}

When to Query

If the gateway returns data.status = 9, use data.task_id with Task Query to retrieve the result. Do not treat a waiting timeout as a failed task and submit it again.

Algorithm Error Example

HTTP status in the source: 400.

{
  "ErrorCode": 20003,
  "ErrorMsg": "detect no face",
  "Data": null
}

API-Specific Error Codes

Error CodeError MessageDescription
20001PROCESS_ERRORProcessing error.

Common Error Codes

See API Error Codes.

SDK Examples

Each example embeds the complete request body and requires no separate JSON file. Replace the AK, SK, and image URL. Set up the signing SDK using the documentation for your language.

The examples submit once and print the response. If the task has not completed, retrieve its result using Task Query.

Python

Python Signing SDK

import json

import requests
from sign_sdk import sign

def main():
    key = "YOUR_ACCESS_KEY"
    secret = "YOUR_SECRET_KEY"
    url = "https://openapi.meitu.com/api/v1/sdk/sync/push"
    params = {
        "parameter": {
            "rsp_media_type": "base64"
        }
    }
    payload = {
        "task": "/v1/clothing_segmentation/488136",
        "task_type": "formula",
        "init_images": [
            {
                "url": "https://example.com/input.png",
                "profile": {
                    "media_profiles": {
                        "media_data_type": "url"
                    },
                    "version": "v1"
                }
            }
        ],
        "params": json.dumps(params, ensure_ascii=True),
        "sync_timeout": 30
    }
    body = json.dumps(payload, ensure_ascii=True)
    headers = {
        "Content-Type": "application/json",
        sign.HeaderHost: "openapi.meitu.com",
    }
    signer = sign.Signer(key, secret)
    signed_request = signer.sign(url, "POST", headers, body)
    with requests.Session() as session:
        response = session.send(
            signed_request, timeout=(10, 60), verify=True, allow_redirects=False
        )
        print("Status:", response.status_code)
        print("Response:", response.text)

if __name__ == "__main__":
    main()

Go

Go Signing SDK

package main

import (
    "fmt"
    "io"
    "net/http"
    "time"

    "github.com/mtlab/api/signer"
)

func main() {
    url := "https://openapi.meitu.com/api/v1/sdk/sync/push"
    body := `{
  "task": "/v1/clothing_segmentation/488136",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://example.com/input.png",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "version": "v1"
      }
    }
  ],
  "params": "{\"parameter\":{\"rsp_media_type\":\"base64\"}}",
  "sync_timeout": 30
}`
    headers := make(http.Header)
    headers.Set("Content-Type", "application/json")
    headers.Set(signer.HeaderHost, "openapi.meitu.com")
    signObj := signer.NewSigner("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY")
    req, err := signObj.Sign(url, http.MethodPost, headers, body)
    if err != nil {
        fmt.Println("Sign request failed:", err)
        return
    }
    client := &http.Client{
        Timeout: 60 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Send request failed:", err)
        return
    }
    defer resp.Body.Close()
    responseBody, err := io.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Read response failed:", err)
        return
    }
    fmt.Println("Status:", resp.StatusCode)
    fmt.Println("Response:", string(responseBody))
}

PHP

PHP Signing SDK

<?php
require_once __DIR__ . '/signer.php';

$params = json_encode([
    'parameter' => [
        'rsp_media_type' => 'base64',
    ],
]);
$body = json_encode([
    'task' => '/v1/clothing_segmentation/488136',
    'task_type' => 'formula',
    'init_images' => [
        [
            'url' => 'https://example.com/input.png',
            'profile' => [
                'media_profiles' => ['media_data_type' => 'url'],
                'version' => 'v1',
            ],
        ],
    ],
    'params' => $params,
    'sync_timeout' => 30,
], JSON_UNESCAPED_SLASHES);
$url = 'https://openapi.meitu.com/api/v1/sdk/sync/push';
$headers = [
    'Content-Type' => 'application/json',
    'Host' => 'openapi.meitu.com',
];
$signer = new Signer('YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY');
$curl = $signer->sign($url, 'POST', $headers, $body);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($curl, CURLOPT_TIMEOUT, 60);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
$response = curl_exec($curl);
if ($response === false) {
    echo 'Error: ' . curl_error($curl) . PHP_EOL;
} else {
    echo 'Status: ' . curl_getinfo($curl, CURLINFO_HTTP_CODE) . PHP_EOL;
    echo 'Response: ' . $response . PHP_EOL;
}
curl_close($curl);

Java

Java Signing SDK

import com.meitu.openai.common.Signer;

import java.io.ByteArrayOutputStream;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;

public class Main {
    public static void main(String[] args) throws Exception {
        String body =
                "{\n" +
                "  \"task\": \"/v1/clothing_segmentation/488136\",\n" +
                "  \"task_type\": \"formula\",\n" +
                "  \"init_images\": [\n" +
                "    {\n" +
                "      \"url\": \"https://example.com/input.png\",\n" +
                "      \"profile\": {\n" +
                "        \"media_profiles\": {\n" +
                "          \"media_data_type\": \"url\"\n" +
                "        },\n" +
                "        \"version\": \"v1\"\n" +
                "      }\n" +
                "    }\n" +
                "  ],\n" +
                "  \"params\": \"{\\\"parameter\\\":{\\\"rsp_media_type\\\":\\\"base64\\\"}}\",\n" +
                "  \"sync_timeout\": 30\n" +
                "}";
        String url = "https://openapi.meitu.com/api/v1/sdk/sync/push";
        Map<String, String> headers = new HashMap<>();
        headers.put("Content-Type", "application/json");
        headers.put(Signer.HeaderHost, "openapi.meitu.com");
        Signer signer = new Signer("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY");
        Map<String, String> signedHeaders = signer.sign(url, "POST", headers, body);
        HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
        try {
            connection.setRequestMethod("POST");
            connection.setConnectTimeout(10000);
            connection.setReadTimeout(60000);
            connection.setInstanceFollowRedirects(false);
            connection.setDoOutput(true);
            for (Map.Entry<String, String> entry : signedHeaders.entrySet()) {
                connection.setRequestProperty(entry.getKey(), entry.getValue());
            }
            byte[] bodyBytes = body.getBytes(StandardCharsets.UTF_8);
            connection.setFixedLengthStreamingMode(bodyBytes.length);
            try (OutputStream output = connection.getOutputStream()) {
                output.write(bodyBytes);
            }
            int status = connection.getResponseCode();
            System.out.println("Status: " + status);
            InputStream stream = status >= 400
                    ? connection.getErrorStream() : connection.getInputStream();
            if (stream != null) {
                try (InputStream input = stream;
                     ByteArrayOutputStream output = new ByteArrayOutputStream()) {
                    byte[] buffer = new byte[4096];
                    int length;
                    while ((length = input.read(buffer)) != -1) {
                        output.write(buffer, 0, length);
                    }
                    System.out.println("Response: " + output.toString("UTF-8"));
                }
            }
        } finally {
            connection.disconnect();
        }
    }
}