AI automatically detects and removes watermark areas from images, returning a clean and natural result image. It works for product photos, posters, 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 an image watermark removal task
/api/tasks/visual/external/watermark-remove Body Parameters
url string optional Source image URL. If this parameter is present, the other image source parameter must be empty.
file file optional Source image file as binary data. If this parameter is present, the other image source parameter must be empty.
For image upload requirements, see Guidelines and Limits #5.
sync integer optional Whether to return the result immediately, default is 0. 0 returns task_id asynchronously and lets you fetch the result later through the query endpoint; 1 waits for the result and returns it immediately. Results are retained for up to 1 hour after submission.
Return Parameters
status number HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.
message string Response message. If the task fails, refer to this field or contact support.
data.task_id string Image watermark removal task ID used for polling.
status number HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.
message string Response message. If the task fails, refer to this field or contact support.
data.task_id string Image watermark removal task ID. If the task fails, contact support with this task_id.
data.created_at string Timestamp of task creation.
data.processed_at string Timestamp when the task started to be processed.
data.completed_at string Timestamp of task completion.
data.file string Result image URL. The URL is valid for 1 hour.
data.progress number Task processing progress.
data.state number Task status. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See Status Code Definitions.
Query image watermark removal result
/api/tasks/visual/external/watermark-remove/{task_id} Path Parameters
task_id string required Task ID returned after creating an async image watermark removal 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 Response message. If the task fails, refer to this field or contact support.
data.task_id string Image watermark removal task ID. If the task fails, contact support with this task_id.
data.created_at string Timestamp of task creation.
data.processed_at string Timestamp when the task started to be processed.
data.completed_at string Timestamp of task completion.
data.file string Result image URL. The URL is valid for 1 hour.
data.progress number Task processing progress.
data.state number Task status. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See Status Code Definitions.
Guidelines and Limits
-
The result image URL is valid for 1 hour. Please download and store it promptly.
-
HTTP status 200 means the HTTP request succeeded; for result queries, status 200 with data.state = 1 means watermark removal succeeded. See Status Code Definitions.
-
When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing issues.
-
You must not use this service for any activity that violates laws, regulations, or the legitimate rights of others.
-
Uploaded images must meet the following format, resolution, and file size limits.
Format Resolution Size jpg, png, bmp Resolution between 20 and 10000 pixels Up to 50MB
# Image Watermark Removal API
Automatically remove watermarks from images and return a clean result image. The API supports asynchronous and synchronous request modes.
> Note: The result image URL is valid for 1 hour. Please 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.
## Request modes
The mode is controlled by the `sync` body parameter:
- Asynchronous (`sync=0`, recommended): the create request returns immediately with `data.task_id`. Poll the query endpoint with that task ID until processing finishes.
- Synchronous (`sync=1`): the create request waits for processing to finish and returns the result directly in the same response.
Result images are retained for up to 1 hour after a successful request.
## Providing the source image
One source image is required, and `url` / `file` are mutually exclusive:
- `url` - source image URL. If this parameter is present, the other image source parameter must be empty.
- `file` - source image file uploaded as `multipart/form-data` binary data. If this parameter is present, the other image source parameter must be empty.
## Endpoints
| Purpose | Method | Path |
| --- | --- | --- |
| Create an image watermark removal task | POST | /api/tasks/visual/external/watermark-remove |
| Query a task result (async) | GET | /api/tasks/visual/external/watermark-remove/{task_id} |
## Create an image watermark removal task
`POST /api/tasks/visual/external/watermark-remove`
Content-Type: `multipart/form-data`
### Body parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| url | string | one of url / file | Source image URL. If this parameter is present, file must be empty. |
| file | file | one of url / file | Source image file as binary data. If this parameter is present, url must be empty. |
| sync | integer | optional | 0 = asynchronous; 1 = synchronous. If sync=0, the API returns task_id and the result can be fetched later through the query endpoint. |
### Return parameters - asynchronous (sync=0)
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP response status code. 200 means the request succeeded, and non-200 means failure. See /states. |
| message | string | Response message. If the task fails, refer to this field or contact support. |
| data.task_id | string | Task ID used for polling. |
### Return parameters - synchronous (sync=1)
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP response status code. 200 means the request succeeded, and non-200 means failure. See /states. |
| message | string | Response message. If the task fails, refer to this field or contact support. |
| data.task_id | string | Task ID. If the task fails, contact support with this task_id. |
| data.created_at | string | Timestamp of task creation. |
| data.processed_at | string | Timestamp when the task started to be processed. |
| data.completed_at | string | Timestamp of task completion. |
| data.file | string | Result image URL. The URL is valid for 1 hour. |
| data.progress | number | Task processing progress. |
| data.state | number | Task status. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See /states. |
### Examples
Asynchronous, image URL:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/external/watermark-remove' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'url=YOUR_IMAGE_URL'
```
Asynchronous, image file:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/external/watermark-remove' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'file=@/path/to/image.jpg'
```
Synchronous, image URL:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/external/watermark-remove' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'url=YOUR_IMAGE_URL'
```
Example async create response:
```json
{
"status": 200,
"message": "success",
"data": { "task_id": "TASK_ID" }
}
```
## Query image watermark removal result
`GET /api/tasks/visual/external/watermark-remove/{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 after creating an async image watermark removal task. |
### Return parameters
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP response status code. 200 means the request succeeded, and non-200 means failure. See /states. |
| message | string | Response message. If the task fails, refer to this field or contact support. |
| data.task_id | string | Task ID. If the task fails, contact support with this task_id. |
| data.created_at | string | Timestamp of task creation. |
| data.processed_at | string | Timestamp when the task started to be processed. |
| data.completed_at | string | Timestamp of task completion. |
| data.file | string | Result image URL. The URL is valid for 1 hour. |
| data.progress | number | Task processing progress. |
| data.state | number | Task status. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See /states. |
### Example
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/external/watermark-remove/{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,
"file": "https://.../result.jpg",
"completed_at": "1634884056"
}
}
```
## Recommended asynchronous flow
1. POST to /api/tasks/visual/external/watermark-remove with `sync=0` and one source image.
2. Read `data.task_id` from the create response.
3. GET /api/tasks/visual/external/watermark-remove/{task_id} every 1 second.
4. Inspect `data.state`: 1 = done (read `data.file`); greater than 1 = keep polling; less than 0 = failed.
5. Download the result image within 1 hour.
## Guidelines and Limits
- The result image URL is valid for **1 hour**. Please download and store it promptly.
- HTTP status 200 means the HTTP request succeeded. For result queries, status 200 with data.state = 1 means watermark removal succeeded. See /states.
- When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing issues.
- You must not use this service for any activity that violates laws, regulations, or the legitimate rights of others.
- Uploaded images must meet the following format, resolution, and file size limits.
| Format | Resolution | File size |
| --- | --- | --- |
| jpg, png, bmp | Resolution between 20 and 10000 pixels | Up to 50MB |
## 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. |