Clothing Segmentation API

Try on PicWish

Segment clothing and portrait regions from an image and return grayscale mask results for selected semantic classes. Supports async and sync request modes for production integrations.

Result links are valid for 1 hour. Please download and store them promptly.

Authentication

Every API request must include your API Key in the X-API-KEY request header. Send it with each request exactly as shown in the examples and parameter descriptions.

X-API-KEY: YOUR_API_KEY

Create a clothing segmentation task

POST /api/tasks/visual/clothing-segmentation

Body Parameters

image_url string optional

Source image URL. Use either image_url or image_file. If this parameter is present, the other image source parameter must be empty.

one required
image_file file optional

Source image file as binary multipart data. Use either image_file or image_url. If this parameter is present, the other image source parameter must be empty.

For image upload requirements, see Guidelines and Limits #4.

sync string | number optional

Whether to wait for and return the result immediately. Results are kept for up to 1 hour.

  • 0: Return a task_id asynchronously and fetch the result later with task_id;
  • 1: Wait for and return the result synchronously.
detail_mode number optional

Segmentation detail mode. Default: 1. Regular fine-grained segmentation is recommended if you do not need all subdivided clothing masks.

  • 1: Regular fine-grained segmentation;
  • 2: Ultra-high fine-grained segmentation.
output_type number optional

Output content. Default: 1.

  • 1: Return only merged masks with the same semantics;
  • 2: Return all subdivided masks with the same semantics in a ZIP file, currently available only for clothing;
  • 3: Return both.
quality number optional

Segmentation quality. Default: 1.

  • 1: Regular segmentation quality;
  • 2: High-precision quality.
class_type number optional

Semantic classes to return. Default: 1.

  • 1: Clothing only: clothes, tops, bottoms, dress, and acc;
  • 2: Fashion items: clothes, tops, bottoms, dress, bag, shoes, and acc;
  • 3: Portrait parts: hair, face, head, and body;
  • 4: Return all classes.

Return Parameters

status number

HTTP response status code. See Status Code Definitions.

  • 200: Request succeeded;
  • Non-200: Request failed.
message string

API response message. Usually success for a successful request.

data.task_id string

Async clothing segmentation task ID returned after the task is created. Use it to query the result later.

status number

HTTP response status code. See Status Code Definitions.

  • 200: Request succeeded;
  • Non-200: Request failed.
message string

API response message. Usually success for a successful request.

data.task_id string

Clothing segmentation task ID.

data.created_at string

Task creation time as a Unix timestamp string.

data.processed_at string

Task processing start time as a Unix timestamp string.

data.completed_at string

Task completion time as a Unix timestamp string.

data.clothes_masks string

ZIP URL for subdivided clothing grayscale masks when returned. The URL is valid for 1 hour.

data.class_masks object

Result mask URLs or base64 data keyed by semantic class, such as acc, body, clothes, face, hair, others, and shoes.

data.output_type number

Returned output type.

data.progress number

Task progress.

  • 100: Processing is complete.
data.state number

Task status code. See Status Code Definitions.

  • 1: Succeeded;
  • > 1: Processing;
  • < 0: Failed.

Query clothing segmentation result

For asynchronous requests, poll the result once every 1 second. The maximum polling duration for this API is 120 seconds; if the total polling time exceeds this without a result, treat it as a timeout failure.

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

Path Parameters

task_id string required

Clothing segmentation task ID returned after creating an async task. Use it to query the processing result.

Return Parameters

status number

HTTP response status code. See Status Code Definitions.

  • 200: Request succeeded;
  • Non-200: Request failed.
message string

API response message. Usually success for a successful request.

data.task_id string

Clothing segmentation task ID.

data.created_at string

Task creation time as a Unix timestamp string.

data.processed_at string

Task processing start time as a Unix timestamp string.

data.completed_at string

Task completion time as a Unix timestamp string.

data.clothes_masks string

ZIP URL for subdivided clothing grayscale masks when returned. The URL is valid for 1 hour.

data.class_masks object

Result mask URLs or base64 data keyed by semantic class, such as acc, body, clothes, face, hair, others, and shoes.

data.output_type number

Returned output type.

data.progress number

Task progress.

  • 100: Processing is complete.
data.state number

Task status code. See Status Code Definitions.

  • 1: Succeeded;
  • > 1: Processing;
  • < 0: Failed.

Guidelines and Limits

  1. Result links are valid for 1 hour. Please download and store them promptly.

  2. HTTP status 200 only means the HTTP request succeeded. Determine task success from status and data.state together.

  3. When passing URLs as parameters, follow URL encoding standards to avoid parameter parsing issues.

  4. Uploaded images must meet the following format, resolution, and file size limits.

    FormatResolutionFile size
    jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzwUp to 4096 x 4096Up to 20MB