Photo Colorization API

# Photo Colorization API

AI colorizes black-and-white photos by restoring natural colors for people, objects, and scenes. It works for old photos, portraits, and design materials, with async and sync 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 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.

## Source image

Exactly one image source is required, and the two options are mutually exclusive:

- `image_url` - source image URL. If this parameter is present, the other image source parameter must be empty.
- `image_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 a photo colorization task | POST | /api/tasks/visual/colorization |
| Query a task result (async) | GET | /api/tasks/visual/colorization/{task_id} |

## Create a photo colorization task

`POST /api/tasks/visual/colorization`

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 parameter 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 parameter must be empty. |
| 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. |
| format | string | optional | Result image format. Supports `jpeg/jpg`, `png`, and `webp`. Default is `jpeg/jpg`. |
| return_type | integer | optional | 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 - asynchronous (sync=0)

| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP response status code. 200 means success, and non-200 means failure. See /states. |
| message | string | API response message. Usually success for a successful request. |
| data.task_id | string | Task ID. Use it to query the result later. |

### Return parameters - synchronous (sync=1)

| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP response status code. 200 means success, and non-200 means failure. See /states. |
| message | string | API response message. Usually success for a successful request. |
| 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.image | string | The URL of the result image 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. -7 means invalid image file. See /states. |

### Examples

Asynchronous, image URL:

```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/colorization' \
-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/colorization' \
-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/colorization' \
-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 colorization 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/colorization/{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 a photo colorization task. |

### Return parameters

| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP response status code. 200 means success, and non-200 means failure. See /states. |
| message | string | API response message. Usually success for a successful request. |
| 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.image | string | The URL of the result image 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. -7 means invalid image file. See /states. |

### Example

```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/colorization/{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/colorization with `sync=0` and exactly one image source (`image_url` or `image_file`). Read `data.task_id`.
2. GET /api/tasks/visual/colorization/{task_id} every 1 second. The polling duration should not exceed 60 seconds.
3. Inspect `data.state`: 1 = done (read `data.image`); greater than 1 = keep polling; less than 0 = failed.
4. Download `data.image` within 1 hour.

## Guidelines and Limits

- The result image URL is valid for 1 hour. Please download and store it promptly.

- Each successful call consumes 1 credit.


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