AI improves blurry or low-quality images by enhancing detail, clarity, and resolution. It works for product photos, portraits, 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 photo enhancement task
/api/tasks/visual/scale Body Parameters
image_url string optional Source image URL. If this parameter is present, the other image source parameters must be empty.
image_file file optional Source image file as binary data. If this parameter is present, the other image source parameters must be empty.
For image upload requirements, see Guidelines and Limits #3.
sync integer optional Whether to return the result image in real time. Use 0 to return a task_id asynchronously and fetch the result later; use 1 to wait and return the result synchronously. Results are kept for up to 1 hour.
type string optional Enhancement type. clean = image enhancement, best for non-portrait images such as products; face = face enhancement, best for portraits. Up to 10 portraits can be enhanced in one image. Default is clean.
scale_factor integer optional Enhancement value. Empty = auto enhancement: (10,512] upscales to 4x, (512,1024] upscales to 2x, and (1024,4096] keeps the original resolution. 1 keeps the original resolution, 2 upscales to 2x, and 4 upscales to 4x.
return_type integer optional Result return type. 1 returns an image URL; 2 returns a base64-encoded string; 3 returns binary data and is only available for synchronized requests. Default is 1.
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 photo enhancement 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 Photo enhancement 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.image string The result image URL or base64 data. The URL is valid for 1 hour.
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 photo enhancement result
/api/tasks/visual/scale/{task_id} Path Parameters
task_id string required Photo enhancement 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 Photo enhancement 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.image string The result image URL or base64 data. The URL is valid for 1 hour.
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
-
The result image URL is valid for 1 hour. Please download and store it promptly.
-
A successful call consumes 2 credits when the long edge is <= 2048px, and 3 credits when 2048px < long edge <= 4096px.
-
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
# Photo Enhancement API
AI improves blurry or low-quality images by enhancing detail, clarity, and resolution. It works for product photos, portraits, and design assets, with 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): 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.
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.
- `image_file` - the raw image file uploaded as `multipart/form-data` binary data.
Do not send both. If `image_url` is present, leave `image_file` empty, and vice versa.
## Endpoints
| Purpose | Method | Path |
| --- | --- | --- |
| Create a photo enhancement task | POST | /api/tasks/visual/scale |
| Query a task result (async) | GET | /api/tasks/visual/scale/{task_id} |
## Create a photo enhancement task
`POST /api/tasks/visual/scale`
Content-Type: `multipart/form-data`
### 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 parameters must be empty. |
| image_file | file | one of image_url / image_file | Source image file as binary data. If this parameter is present, the other image source parameters must be empty. |
| sync | integer | optional | 0 = asynchronous; 1 = synchronous. Results are kept up to 1 hour. |
| type | string | optional | Enhancement type. `clean` = image enhancement for non-portrait images such as products; `face` = face enhancement for portraits. Up to 10 portraits can be enhanced in one image. Default is `clean`. |
| scale_factor | integer | optional | Enhancement value. Empty = auto enhancement: (10,512] upscales to 4x, (512,1024] upscales to 2x, and (1024,4096] keeps the original resolution. 1 keeps original resolution; 2 upscales to 2x; 4 upscales to 4x. |
| return_type | integer | optional | 1 = image URL; 2 = base64-encoded string; 3 = binary data, only available for synchronized requests. Default is 1. |
### 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 | 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.image | string | The result image URL or base64 data. URL results are valid for 1 hour. |
| data.progress | number | Task 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/scale' \
-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/scale' \
-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/scale' \
-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 photo enhancement result
`GET /api/tasks/visual/scale/{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.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.image | string | The result image URL or base64 data. URL results are valid for 1 hour. |
| data.progress | number | Task 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/scale/{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.jpg",
"completed_at": "1700000000"
}
}
```
## Recommended asynchronous flow
1. POST to /api/tasks/visual/scale with `sync=0` and exactly one image source (`image_url` or `image_file`). Read `data.task_id`.
2. GET /api/tasks/visual/scale/{task_id} every 1-2 seconds.
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.
- A successful call consumes 2 credits when the long edge is <= 2048px, and 3 credits when 2048px < long edge <= 4096px.
- 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. |