Image Watermark Removal API

# 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

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

`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. |