老照片修复API

# 老照片修复 API

通过 API 修复和增强老照片，修复破损、提升清晰度，并可选择对照片进行上色，支持异步与同步两种调用方式。

> 注意：接口返回的结果图片链接有效期为 1 小时，请及时下载并存储。

## 接口域名（Base URL）

以下路径均基于接口域名：

```
https://techsz.aoscdn.com
```

## 鉴权

每个请求都必须在请求头中携带你的 API Key：

```http
X-API-KEY: YOUR_API_KEY
```

你可以在 [API Key](https://picwish.cn/my-account?subRoute=api-key) 页面获取或管理 X-API-KEY。

未携带有效 API Key 的请求会被拒绝。

## 调用方式

通过创建请求中的 `sync` 参数选择调用方式：

- 异步（`sync=0`，推荐）：创建请求立即返回 `data.task_id`，随后用该任务 ID 轮询查询接口直到处理完成。
- 同步（`sync=1`）：创建请求等待处理完成，并在同一个响应中直接返回结果。

异步轮询整体时长建议不超过 180 秒，轮询间隔推荐 1 秒。

## 原图来源

`image_file` 与 `image_url` 二者必选其一；如果同时传入，优先级为 `image_file > image_url`：

- `image_url`：图片下载地址，支持 HTTP 协议和 OSS 协议，最长 512 个字符，下载超时 10 秒。
- `image_file`：以 `multipart/form-data` 上传的图片文件（二进制）。

## 接口列表

| 用途 | 请求方式 | 路径 |
| --- | --- | --- |
| 创建老照片修复任务 | POST | /api/tasks/visual/restoration-old-photo |
| 查询任务结果（异步） | GET | /api/tasks/visual/restoration-old-photo/{task_id} |

## 创建老照片修复任务

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

Content-Type: `multipart/form-data`

### 请求参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| image_url | string | image_url / image_file 二选一 | 图片下载地址。支持 HTTP 协议和 OSS 协议，最长 512 个字符，下载超时 10 秒。如果同时传入 image_url 与 image_file，优先使用 image_file。 |
| image_file | file | image_url / image_file 二选一 | 图片文件。支持 JPG、JPEG、PNG 格式。如果同时传入 image_file 与 image_url，优先使用 image_file。服务端接收到的输入图片需小于 20MB，分辨率最大 2048x2048。 |
| sync | integer | 可选 | 0 = 异步返回 task_id，稍后轮询结果；1 = 同步等待并直接返回结果。异步示例默认 0，同步示例默认 1。 |
| restoration_type | integer | 可选 | 图片破损类型。0 = 轻微（默认）；1 = 中等；2 = 严重。 |
| model_type | integer | 可选 | 模型。仅在 restoration_type > 0 时生效。1 = 真实还原；2 = 智能优化；3 = 超清还原。 |
| change_color | integer | 可选 | 改变颜色。0 = 不改变；1 = 改变（默认）。 |

### 返回参数 - 异步（sync=0）

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | number | HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败。详见 /states。 |
| message | string | 返回说明。任务失败时可参考此字段或联系客服。 |
| data.task_id | string | 任务 ID，用于轮询结果。 |

### 返回参数 - 同步（sync=1）

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | number | HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败。详见 /states。 |
| message | string | 返回说明。任务失败时可参考此字段或联系客服。 |
| data.task_id | string | 任务 ID。 |
| data.created_at | string | 任务创建时间戳。 |
| data.processed_at | string | 任务开始处理时间戳。 |
| data.completed_at | string | 任务完成时间戳。 |
| data.image | string | 结果图 URL 或 Base64 数据。 |
| data.image_url | string | 结果图 URL，部分示例使用该字段名。 |
| data.return_type | number | 结果返回方式。 |
| data.progress | number | 任务进度百分比，取值范围 0~100。 |
| data.state | number | 1 表示完成；0 或大于 1 表示处理中；小于 0 表示失败。详见 /states。 |
| data.state_detail | string | 任务状态详情。 |
| data.download_time | number | 下载耗时。 |
| data.time_elapsed | string | 总耗时。 |

### 示例

异步，使用图片 URL：

```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/restoration-old-photo' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'image_url=YOUR_IMAGE_URL'
```

异步，上传本地文件：

```bash
curl -k 'https://techsz.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'
```

同步，直接返回结果：

```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/restoration-old-photo' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_url=YOUR_IMAGE_URL'
```

异步创建响应示例：

```json
{
  "status": 200,
  "message": "success",
  "data": { "task_id": "TASK_ID" }
}
```

## 查询老照片修复结果

异步请求建议每 **1 秒** 轮询一次结果，本接口最大轮询时长为 **180 秒**；累计轮询超过该时长仍未返回结果，即可视为超时失败。

`GET /api/tasks/visual/restoration-old-photo/{task_id}`

异步模式下用于轮询获取结果。

### 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| task_id | string | 必填 | 创建任务且 sync=0 时返回的任务 ID。 |

### 返回参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | number | HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败。详见 /states。 |
| message | string | 返回说明。任务失败时可参考此字段或联系客服。 |
| data.task_id | string | 任务 ID。 |
| data.created_at | string | 任务创建时间戳。 |
| data.processed_at | string | 任务开始处理时间戳。 |
| data.completed_at | string | 任务完成时间戳。 |
| data.image | string | 结果图 URL 或 Base64 数据。 |
| data.image_url | string | 结果图 URL，部分示例使用该字段名。 |
| data.return_type | number | 结果返回方式。 |
| data.progress | number | 任务进度百分比，取值范围 0~100。 |
| data.state | number | 1 表示完成；0 或大于 1 表示处理中；小于 0 表示失败。详见 /states。 |
| data.state_detail | string | 任务状态详情。 |
| data.download_time | number | 下载耗时。 |
| data.time_elapsed | string | 总耗时。 |

### 示例

```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/restoration-old-photo/{task_id}' \
-H 'X-API-KEY: YOUR_API_KEY'
```

处理完成响应示例：

```json
{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "TASK_ID",
    "state": 1,
    "progress": 100,
    "image": "https://.../result.jpg",
    "completed_at": "1634884056"
  }
}
```

## 推荐异步流程

1. 使用 `sync=0` 和一种图片来源（`image_url` 或 `image_file`）POST 到 /api/tasks/visual/restoration-old-photo，读取 `data.task_id`。
2. 每隔 1 秒 GET /api/tasks/visual/restoration-old-photo/{task_id}，整体轮询时长建议不超过 180 秒。
3. 检查 `data.state`：1 = 完成（读取 `data.image` 或 `data.image_url`）；0 或 > 1 = 继续轮询；< 0 = 失败。
4. 在 1 小时内下载结果图片。

## 使用规范与限制

- 接口返回的链接有效期为 **1 小时**，请及时下载存储。

- HTTP status 为 200 表示 HTTP 请求成功，并非老照片修复处理成功，任务结果请结合 data.state 判断，详见状态码说明。

- 使用 URL 传参时，请按照 URL 编码规范处理，避免参数解析异常。


- 上传图片需符合以下格式、分辨率和大小限制。

| 格式 | 分辨率 | 大小 |
| --- | --- | --- |
| jpg, jpeg, png | 最大 2048x2048 | 小于20MB |

## 状态码

任务是否成功，需要结合 HTTP 响应状态码（`status`）和任务状态码（`data.state`）共同判断。

### HTTP 响应状态码

| 状态码 | 说明 |
| --- | --- |
| 200 | 请求成功。 |
| 400 | 客户端参数传递错误。请检查参数是否缺失或值是否正确。 |
| 401 | 认证失败。请检查 X-API-KEY 是否正确或服务是否开通。 |
| 404 | 请求的 URL 或资源不存在。请检查 URL 或 task_id 是否正确。 |
| 413 | 上传的文件超出大小限制。请参见各服务的最大文件限制。 |
| 429 | 请求频率超出 QPS 限制（默认 QPS 为 2）。请放缓请求速率，或联系商务提升 QPS。 |
| 500 | 服务端异常。请反馈给商务或技术对接人员。 |

### 任务状态码（data.state）

1 = 成功；大于 1 = 处理中；小于 0 = 失败。

| 状态码 | 说明 |
| --- | --- |
| -17 | 处理失败，非法提示词。 |
| -16 | 处理失败，使用第三方检测发现违规。 |
| -15 | 处理失败，资源不足。 |
| -14 | 处理失败，输入图片内容不符合要求。 |
| -13 | 处理失败，任务异常被取消。 |
| -11 | 处理失败，结果为空。 |
| -10 | 处理失败，内部检测非法。 |
| -9 | 处理失败，内部程序循环处理失败。 |
| -8 | 处理超时，最长处理时间 180 秒。 |
| -7 | 无效图片文件（如图片损坏、格式不对等）。 |
| -5 | image_url 图片超出大小限制（30MB）。 |
| -3 | 服务器下载图片文件失败，请检查图片 URL 是否可用。 |
| -2 | 处理完成，但上传 OSS 失败。 |
| -1 | 处理失败。 |
| 0 | 排队中，任务正在队列中等待。 |
| 1 | 完成，处理成功。 |
| 2 | 准备中。 |
| 3 | 等待中。 |
| 4 | 处理中，正在进行。 |
| 5 | 内部发布处理中。 |
| 6 | 处理中，内部循环处理中。 |