AI detects the main subject in an image, removes the background in one step, and outputs a high-quality transparent PNG. It works for ecommerce product photos, portraits, ID photos, and design assets, with async and sync request modes.
The result image URL is valid for 1 hour. Please download and store it 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 background removal task
/api/tasks/visual/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 parameters must be empty.
image_file file optional Source image file as binary data. Use either image_file or image_url. If this parameter is present, the other image source parameters must be empty.
For image upload requirements, see Guidelines and Limits #2.
sync string | number optional Whether to wait for the result and return it immediately. Results are kept for up to 1 hour.
0: Returns atask_idasynchronously. Use thetask_idto retrieve the result later.1: Waits for processing to complete and returns the result synchronously.
type string optional Foreground type. If omitted, the foreground is detected automatically (default).
person: People;object: Objects;stamp: Stamps.
return_type number optional Result return format.
1: Image download URL;2: Base64-encoded string;3: Binary stream (available for synchronous requests only).
output_type number optional Result image option.
1: Image and mask;2: Image only (default);3: Mask only.
crop number optional Whether to crop to the subject edge.
0: Keeps the original image size (default);1: Crops to the subject edge.
format string optional Result image format.
png: Transparent-background image (default);jpg: White-background image. Use withbg_colorto set the background color.
bg_color string optional Adds a solid color background using a hex color value, such as 81d4fa or ffffff. This parameter is effective only when format=jpg. If it is used, ensure the other bg_ parameters are empty.
bg_image_file file optional Adds a custom background image file. The image is centered and scaled to fill the canvas while preserving its aspect ratio; excess edges are cropped. Limits: file size up to 20MB and resolution up to 4K. If this parameter is used, ensure the other bg_ parameters are empty.
bg_image_url string optional Adds a custom background image URL. The image is centered and scaled to fill the canvas while preserving its aspect ratio; excess edges are cropped. Limits: file size up to 20MB and resolution up to 4K. If this parameter is used, ensure the other bg_ parameters are empty.
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 background removal 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 Background removal 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.image string Background removal result image URL. Whether it is returned depends on return_type, output_type, format, and related parameters. The URL is valid for 1 hour.
data.mask string Mask image URL. Returned only when the selected output option includes a mask. The URL is valid for 1 hour.
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 background removal result
For asynchronous requests, poll the result once every 1 second. The maximum polling duration for this API is 60 seconds; if the total polling time exceeds this without a result, treat it as a timeout failure.
/api/tasks/visual/segmentation/{task_id} Path Parameters
task_id string required Background removal 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 Background removal 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.image string Background removal result image URL. Whether it is returned depends on return_type, output_type, format, and related parameters. The URL is valid for 1 hour.
data.mask string Mask image URL. Returned only when the selected output option includes a mask. The URL is valid for 1 hour.
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
-
The result image URL is valid for 1 hour. Please download and store it promptly.
-
Uploaded images must meet the following format, resolution, and file size limits.
Format Resolution Size jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw Up to 4096 x 4096 Up to 20MB
# Background Removal API
AI detects the main subject in an image, removes the background in one step, and returns a high-quality transparent PNG. It works for e-commerce product photos, portraits, ID photos, and design assets, and supports both asynchronous and synchronous request modes.
> Note: Every result image URL is valid for 1 hour. Download and store it 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).
Requests without a valid key are rejected.
## Choosing a request mode (sync vs async)
The mode is controlled by the `sync` body parameter on the create request:
- Asynchronous (`sync=0`, recommended for large images or batch jobs): the create request returns immediately with a `task_id`. You then poll the query endpoint with that `task_id` until processing finishes. This avoids long-held connections and timeouts.
- Synchronous (`sync=1`): the create request blocks until processing finishes and returns the result directly in the same response. Simpler, but the connection is held until the image is ready.
In both modes, results are retained for up to 1 hour.
## Providing the source image (image_url vs image_file)
Exactly one image source is required, and the two options are mutually exclusive:
- `image_url` - a publicly reachable URL of the source image, sent as a normal form field.
- `image_file` - the raw image file uploaded as `multipart/form-data` (binary).
Do not send both. If `image_url` is present, leave `image_file` empty, and vice versa.
## Endpoints
| Purpose | Method | Path |
| --- | --- | --- |
| Create a background-removal task | POST | /api/tasks/visual/segmentation |
| Query a task result (async) | GET | /api/tasks/visual/segmentation/{task_id} |
## Create a background-removal task
`POST /api/tasks/visual/segmentation`
Content-Type: `multipart/form-data`
### Body parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| image_url | string | one of image_url / image_file | Source image URL. Mutually exclusive with image_file. |
| image_file | file | one of image_url / image_file | Source image as binary (multipart). Mutually exclusive with image_url. |
| sync | string \| number | optional | 0 = asynchronous (returns task_id, poll later); 1 = synchronous (returns the result directly). Results are kept up to 1 hour. |
| type | string | optional | Foreground type. Empty = auto-detect; `person` = people; `object` = products/objects; `stamp` = stamps. |
| return_type | number | optional | Result format. 1 = image URL; 2 = base64 string; 3 = binary (synchronous requests only). |
| output_type | number | optional | 1 = image + mask; 2 = image only (default); 3 = mask only. |
| crop | number | optional | 0 = keep the original image size (default); 1 = crop to the subject edge. |
| format | string | optional | `png` = transparent PNG (default); `jpg` = white-background JPG (can combine with bg_color). |
| bg_color | string | optional | Solid background hex such as 81d4fa or ffffff. Only effective when format=jpg. Keep other bg_ params empty when used. |
| bg_image_file | file | optional | Custom background image file. Centered and scaled to fill while preserving aspect ratio; excess edges are cropped. Max 20MB, up to 4K. Keep other bg_ params empty. |
| bg_image_url | string | optional | Custom background image URL. Same behavior and limits as bg_image_file. Keep other bg_ params empty. |
### 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)
The finished task data is returned directly, with the same shape as the query response below.
### Examples
Asynchronous, image URL:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/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/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/segmentation' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_url=YOUR_IMAGE_URL'
```
Example async create response:
```json
{
"status": 200,
"message": "success",
"data": { "task_id": "TASK_ID" }
}
```
## Query background-removal result
For asynchronous requests, poll the result once every **1 second**. The maximum polling duration for this API is **60 seconds**; if the total polling time exceeds this without a result, treat it as a timeout failure.
`GET /api/tasks/visual/segmentation/{task_id}`
Use this 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.state | number | 1 = succeeded; > 1 = still processing; < 0 = failed. See /states. |
| data.progress | number | Progress; 100 means processing is complete. |
| data.image | string | Result image URL (depends on return_type / output_type / format). Valid for 1 hour. |
| data.mask | string | Mask image URL, returned when the output option includes a mask. Valid for 1 hour. |
| data.created_at | string | Task creation time (Unix timestamp string). |
| data.processed_at | string | Processing start time (Unix timestamp string). |
| data.completed_at | string | Completion time (Unix timestamp string). |
### Example
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/segmentation/{task_id}' \
-H 'X-API-KEY: YOUR_API_KEY'
```
Example completed response:
```json
{
"status": 200,
"message": "success",
"data": {
"task_id": "TASK_ID",
"state": 1,
"progress": 100,
"image": "https://.../result.png",
"completed_at": "1700000000"
}
}
```
## Recommended asynchronous flow
1. POST to /api/tasks/visual/segmentation with `sync=0` and exactly one image source (`image_url` or `image_file`). Read `data.task_id`.
2. GET /api/tasks/visual/segmentation/{task_id} every 1 second.
3. Inspect `data.state`: 1 = done (read `data.image`); > 1 = keep polling; < 0 = failed.
4. Download `data.image` within 1 hour.
## Guidelines and Limits
- The URL of the result image is valid for **1 hour**. Please download the image file promptly.
- 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. |