Old Photo Restoration API

# Old Photo Restoration API

Restore and enhance old photos programmatically. The API repairs damage, improves clarity, and can optionally colorize the result, with 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.

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

We recommend keeping async polling within 180 seconds and polling once every 1 second.

## Providing the source image (image_url vs image_file)

`image_file` and `image_url` are one-of-two required. If both are provided, `image_file` takes priority over `image_url`:

- `image_url` - image download URL. HTTP and OSS URLs are supported, up to 512 characters, with a 10-second download timeout.
- `image_file` - image file uploaded as `multipart/form-data` binary data.

## Endpoints

| Purpose | Method | Path |
| --- | --- | --- |
| Create an old photo restoration task | POST | /api/tasks/visual/restoration-old-photo |
| Query a task result (async) | GET | /api/tasks/visual/restoration-old-photo/{task_id} |

## Create an old photo restoration task

`POST /api/tasks/visual/restoration-old-photo`

Content-Type: `multipart/form-data`

### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| image_url | string | one of image_url / image_file | Image download URL. Supports HTTP and OSS URLs, up to 512 characters, with a 10-second download timeout. If both image_url and image_file are sent, image_file takes priority. |
| image_file | file | one of image_url / image_file | Image file. Supported formats: JPG, JPEG, PNG. If both image_file and image_url are sent, image_file takes priority. The server-received image must be less than 20MB and up to 2048 x 2048. |
| sync | integer | optional | 0 = asynchronous; 1 = synchronous. Default is 0 for async examples and 1 for sync examples. |
| restoration_type | integer | optional | Damage level. 0 = light (default); 1 = medium; 2 = severe. |
| model_type | integer | optional | Model type. Only takes effect when restoration_type > 0. 1 = realistic restoration; 2 = smart enhancement; 3 = Ultra HD restoration. |
| change_color | integer | optional | Whether to change color. 0 = do not change; 1 = change color (default). |

### 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. |
| data.created_at | string | Task creation timestamp. |
| data.processed_at | string | Timestamp when processing started. |
| data.completed_at | string | Task completion timestamp. |
| data.image | string | Result image URL or Base64 data. |
| data.image_url | string | Result image URL. Some examples use this field name. |
| data.return_type | number | Result return type. |
| data.progress | number | Task progress percentage, ranging from 0 to 100. |
| data.state | number | 1 = completed; 0 or > 1 = still processing; < 0 = failed. See /states. |
| data.state_detail | string | Detailed task state. |
| data.download_time | number | Download time. |
| data.time_elapsed | string | Total processing time. |

### Examples

Asynchronous, image URL:

```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/restoration-old-photo' \
-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/restoration-old-photo' \
-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/restoration-old-photo' \
-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 old photo restoration result

`GET /api/tasks/visual/restoration-old-photo/{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 the task with sync=0. |

### 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. |
| data.created_at | string | Task creation timestamp. |
| data.processed_at | string | Timestamp when processing started. |
| data.completed_at | string | Task completion timestamp. |
| data.image | string | Result image URL or Base64 data. |
| data.image_url | string | Result image URL. Some examples use this field name. |
| data.return_type | number | Result return type. |
| data.progress | number | Task progress percentage, ranging from 0 to 100. |
| data.state | number | 1 = completed; 0 or > 1 = still processing; < 0 = failed. See /states. |
| data.state_detail | string | Detailed task state. |
| data.download_time | number | Download time. |
| data.time_elapsed | string | Total processing time. |

### Example

```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/restoration-old-photo/{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": "1634884056"
  }
}
```

## Recommended asynchronous flow

1. POST to /api/tasks/visual/restoration-old-photo with `sync=0` and one image source (`image_url` or `image_file`). Read `data.task_id`.
2. GET /api/tasks/visual/restoration-old-photo/{task_id} every 1 second. Keep total polling under 180 seconds.
3. Inspect `data.state`: 1 = done (read `data.image` or `data.image_url`); > 1 or 0 = keep polling; < 0 = failed.
4. Download the result image within 1 hour.

## Guidelines and Limits

- The URL of the result image is valid for **1 hour**. Please download the image file promptly.

- HTTP status 200 means the HTTP request succeeded, not that old photo restoration succeeded. Check data.state for the task result. See Status Code Definitions.

- When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing issues.


- Uploaded images must meet the following format, resolution, and file size limits.

| Format | Resolution | File size |
| --- | --- | --- |
| jpg, jpeg, png | Up to 2048 x 2048 | Less than 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. |