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
/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.
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 the result and return it immediately. Use 0 to return a task_id asynchronously, then fetch the result later with the task_id. Use 1 to wait and return the result synchronously. Results are kept for up to 1 hour.
detail_mode number optional Segmentation detail mode. 1 = fine-grained regular (default). 2 = fine-grained ultra-high. Regular fine-grained segmentation is recommended if you do not need full clothing subdivision grayscale images.
output_type number optional Output content. 1 = only merged grayscale masks with the same semantics (default). 2 = all subdivided grayscale masks with the same semantics packaged as a ZIP file, currently only for clothing. 3 = return both.
quality number optional Segmentation quality. 1 = regular segmentation quality (default); 2 = high precision quality.
class_type number optional Semantic classes to return. 1 = clothing parts only: clothes, tops, bottoms, dress, acc (default). 2 = fashion parts: clothes, tops, bottoms, dress, bag, shoes, acc. 3 = portrait parts: hair, face, head, body. 4 = return all: hair, face, head, clothes, tops, bottoms, dress, bag, shoes, acc, body, others.hair = hair, face = face, head = head, clothes = clothes, shoes = shoes, bag = bag, acc = accessories, tops = tops, bottoms = bottoms, dress = dress, body = body, others = others.
Return Parameters
status number HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.
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. 200 means success, and non-200 means failure. See Status Code Definitions.
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 means processing is complete.
data.state number Task status code. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. See Status Code Definitions.
Query clothing segmentation result
/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. 200 means success, and non-200 means failure. See Status Code Definitions.
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 means processing is complete.
data.state number Task status code. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. See Status Code Definitions.
Guidelines and Limits
-
Result links are valid for 1 hour. Please download and store them promptly.
-
HTTP status 200 only means the HTTP request succeeded. Determine task success from status and data.state together.
-
When passing URLs as parameters, follow URL encoding standards to avoid parameter parsing issues.
-
Uploaded images must meet the following format, resolution, and file size limits.
Format Resolution File size jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw Up to 4096 x 4096 Up to 20MB
# Clothing Segmentation API
Segment clothing and portrait regions from an image and return grayscale mask results for selected semantic classes. The API supports asynchronous and synchronous request modes.
> Note: Result links are valid for 1 hour. Download and store them promptly.
## Base URL
All paths below are relative to the Base URL:
```
https://techhk.aoscdn.com
```
## Authentication
Every request must include your API key in the `X-API-KEY` request header:
```http
X-API-KEY: YOUR_API_KEY
```
Get or manage your API key from [API Key](https://picwish.com/my-account?subRoute=api-key).
## Request modes
The mode is controlled by the `sync` body parameter:
- Asynchronous (`sync=0`): the create request returns `data.task_id`, then you poll the query endpoint until processing finishes.
- Synchronous (`sync=1`): the create request waits for processing to finish and returns the result directly.
Results are kept for up to 1 hour after a successful request.
## Source image
Exactly one source image is required:
- `image_url` - a publicly reachable image URL.
- `image_file` - the raw image file uploaded as multipart binary data.
Do not send both at the same time.
## Endpoints
| Purpose | Method | Path |
| --- | --- | --- |
| Create a clothing segmentation task | POST | /api/tasks/visual/clothing-segmentation |
| Query a task result (async) | GET | /api/tasks/visual/clothing-segmentation/{task_id} |
## Create a clothing segmentation task
`POST /api/tasks/visual/clothing-segmentation`
Content-Type: `multipart/form-data`
A successful call consumes 3 credits.
### Body parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| image_url | string | one of image_url / image_file | Source image URL. If this parameter is present, the other image source parameter must be empty. |
| image_file | file | one of image_url / image_file | Source image file as binary multipart data. If this parameter is present, the other image source parameter must be empty. |
| sync | string \| number | optional | 0 = asynchronous, returns `task_id`; 1 = synchronous, waits for the result and returns it directly. Results are kept up to 1 hour. |
| detail_mode | number | optional | 1 = fine-grained regular (default); 2 = fine-grained ultra-high. Regular fine-grained segmentation is recommended if you do not need full clothing subdivision grayscale images. |
| output_type | number | optional | 1 = merged grayscale masks with the same semantics (default); 2 = all subdivided grayscale masks with the same semantics in a ZIP file, currently only for clothing; 3 = return both. |
| quality | number | optional | 1 = regular segmentation quality (default); 2 = high precision quality. |
| class_type | number | optional | 1 = clothing parts only: clothes, tops, bottoms, dress, acc (default). 2 = fashion parts: clothes, tops, bottoms, dress, bag, shoes, acc. 3 = portrait parts: hair, face, head, body. 4 = return all: hair, face, head, clothes, tops, bottoms, dress, bag, shoes, acc, body, others. |
Class label meanings: `hair` = hair, `face` = face, `head` = head, `clothes` = clothes, `shoes` = shoes, `bag` = bag, `acc` = accessories, `tops` = tops, `bottoms` = bottoms, `dress` = dress, `body` = body, `others` = others.
### Return parameters - asynchronous (sync=0)
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP-style status code. 200 = success, non-200 = failure. See /states. |
| message | string | Response message. Usually "success". |
| data.task_id | string | Task ID. Use it to query the result later. |
### Return parameters - synchronous (sync=1)
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP-style status code. 200 = success, non-200 = failure. See /states. |
| message | string | Response message. Usually "success". |
| data.task_id | string | 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. Valid for 1 hour. |
| data.class_masks | object | Result mask URLs or base64 data keyed by semantic class. |
| data.output_type | number | Returned output type. |
| data.progress | number | Progress; 100 means processing is complete. |
| data.state | number | 1 = succeeded; > 1 = still processing; < 0 = failed. See /states. |
### Examples
Asynchronous, image URL:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/clothing-segmentation' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'image_url=YOUR_IMAGE_URL'
```
Asynchronous, image file upload:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/clothing-segmentation' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'image_file=@/path/to/image.jpg'
```
Synchronous (result returned directly):
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/clothing-segmentation' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_url=YOUR_IMAGE_URL'
```
## Query clothing segmentation result
`GET /api/tasks/visual/clothing-segmentation/{task_id}`
Use this endpoint in asynchronous mode to poll for the result.
### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| task_id | string | required | The task ID returned by the create request. |
### Return parameters
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP-style status code. 200 = success, non-200 = failure. See /states. |
| message | string | Response message. Usually "success". |
| data.task_id | string | 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. Valid for 1 hour. |
| data.class_masks | object | Result mask URLs or base64 data keyed by semantic class. |
| data.output_type | number | Returned output type. |
| data.progress | number | Progress; 100 means processing is complete. |
| data.state | number | 1 = succeeded; > 1 = still processing; < 0 = failed. See /states. |
### Example
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/clothing-segmentation/{task_id}' \
-H 'X-API-KEY: YOUR_API_KEY'
```
## Recommended asynchronous flow
1. POST to /api/tasks/visual/clothing-segmentation with `sync=0` and exactly one image source.
2. Read `data.task_id` from the create response.
3. GET /api/tasks/visual/clothing-segmentation/{task_id} every 1-2 seconds. Keep polling for up to about 30 seconds unless your integration defines a longer timeout.
4. Inspect `data.state`: 1 = done; > 1 = keep polling; < 0 = failed.
5. Download returned mask links within 1 hour.
## Guidelines and Limits
- Result links are valid for **1 hour**. Download and store them promptly.
- HTTP status 200 only means the HTTP request succeeded. Determine task success from `status` and `data.state` together.
- When passing URLs as parameters, follow URL encoding standards to avoid parameter parsing issues.
- Uploaded images must meet the following format, resolution, and file size limits.
| Format | Resolution | File size |
| --- | --- | --- |
| jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw | Up to 4096 x 4096 | Up to 20MB |
## Status codes
Determine success by combining the HTTP response status code (`status`) with the task status code (`data.state`).
### HTTP response status codes
| Code | Meaning |
| --- | --- |
| 200 | The request is successful. |
| 400 | Wrong parameter passed by the client. Check whether a parameter is missing or has an incorrect value. |
| 401 | Unauthorized API key. Check that X-API-KEY is correct and the service is enabled. |
| 404 | The requested URL or resource does not exist. Check that the URL or task_id is correct. |
| 413 | The uploaded file exceeds the allowed size. Refer to the supported image size. |
| 429 | Request frequency exceeds the QPS limit (default QPS is 2). Slow down or contact us to raise your QPS. |
| 500 | Server-side exception. Please contact support. |
### Task status codes (data.state)
1 = succeeded; greater than 1 = still processing; less than 0 = failed.
| Code | Meaning |
| --- | --- |
| -17 | Processing failed because the prompt is invalid. |
| -16 | Processing failed because a third-party review detected prohibited content. |
| -15 | Processing failed due to insufficient resources. |
| -14 | Processing failed because the input image content does not meet the requirements. |
| -13 | Processing failed because the task was canceled due to an exception. |
| -11 | Processing failed because the result is empty. |
| -10 | Processing failed because internal review detected prohibited content. |
| -9 | Processing failed because the internal program failed during loop processing. |
| -8 | Processing timed out. The maximum processing time is 180 seconds. |
| -7 | Invalid image file (e.g. corrupted image or incorrect format). |
| -5 | The image_url image exceeds the size limit (30MB). |
| -3 | The server failed to download your file. Check that the source image URL is available. |
| -2 | Processing completed, but uploading the result to OSS failed. |
| -1 | Processing failed. |
| 0 | Queued. The task is waiting in the queue. |
| 1 | Completed. Processing succeeded. |
| 2 | Preparing. |
| 3 | Waiting. |
| 4 | Processing in progress. |
| 5 | Internally publishing the result. |
| 6 | Processing. Internal loop processing is in progress. |