将彩色图片转换为黑白效果，并支持调节灰度强度。适用于人物、商品、印章等图像处理场景，支持异步、同步两种调用方式。
接口返回的结果图片链接一般有效期为 1 小时，请及时下载并存储。
鉴权
每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。
X-API-KEY: YOUR_API_KEY 创建图片黑白化任务
POST
/api/tasks/visual/grayscale-conversion 请求参数
image_url string 可选 图片下载地址。支持 HTTP 和 OSS 协议，最长 512 个字符，下载超时 20 秒。三种图片来源同时传入时，优先级低于 image_file、高于 image_base64。
三选一必填
image_base64 string 可选 图片的 base64 编码。编码后数据量会增加约 33%，不推荐使用；三种图片来源中优先级最低。
三选一必填
sync integer 可选 是否同步返回。 默认值为 0。
0：异步返回task_id，随后通过task_id轮询结果；1：同步等待处理完成并直接返回结果。
type string 可选 前景类型。不填时自动识别（默认）。
person：人物；object：物体；stamp：印章。
gray_strength string 可选 灰度强度，范围为 1～10，默认值为 5。值越小效果越暗，值越大效果越亮。
返回参数
message string 接口返回消息。
data.task_id string 异步任务 ID，用于后续查询图片黑白化结果。
message string 接口返回消息。任务失败时可携带该消息联系商务或技术支持。
data.task_id string 图片黑白化任务 ID。
data.created_at integer 任务创建时间戳。
data.processed_at integer 任务开始处理的时间戳。
data.completed_at integer 任务完成时间戳。
data.image string 黑白化结果图片下载 URL 或 base64 数据；URL 有效期一般为 1 小时。
data.gray_strength integer 模糊程度。
data.output_type integer 图片输出类型。
data.return_type integer 结果返回方式。
data.progress integer 任务处理进度，范围为 0～100。
100：处理完成。
data.result_type string 服务实际识别的黑白化类型：person、object 或 stamp。
data.type string 请求指定的前景类型。
auto：自动识别。
data.time_elapsed string 任务处理耗时。
data.use_point integer 扣费点数。
查询图片黑白化结果
异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 300 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。
GET
/api/tasks/visual/grayscale-conversion/{task_id} 路径参数
task_id string 必填 图片黑白化任务 ID。创建异步任务后返回，用于查询任务处理结果。
返回参数
message string 接口返回消息。任务失败时可携带该消息联系商务或技术支持。
data.task_id string 图片黑白化任务 ID。任务失败时，可携带该参数联系商务或技术支持。
data.created_at integer 任务创建时间戳。
data.processed_at integer 任务开始处理的时间戳。
data.completed_at integer 任务完成时间戳。
data.image string 黑白化结果图片下载 URL 或 base64 数据；URL 有效期一般为 1 小时。
data.gray_strength integer 模糊程度。
data.progress integer 任务处理进度，范围为 0～100。
100：处理完成。
data.result_type string 服务实际识别的黑白化类型：person、object 或 stamp。
data.type string 请求指定的前景类型。
auto：自动识别。
data.time_elapsed string 任务处理耗时。
data.use_point integer 扣费点数。
使用规范与限制
-
接口返回的结果图片链接一般有效期为 1 小时，请及时下载并存储。
-
HTTP status 为 200 仅表示 HTTP 请求成功，并不表示图片黑白化成功；请结合 data.state 判断任务结果。
-
使用 URL 作为参数时，请遵守 URL 编码规范，避免参数解析混乱。
-
每次成功调用消耗 15 点。
-
上传图片需符合以下格式、分辨率和大小限制。
格式 分辨率 大小 jpg, jpeg, bmp, png, webp, tiff, bitmap 最大 4096x4096 最大20MB
查看 Markdown
# 图片黑白化 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。
## 调用方式
- 异步（`sync=0`，默认）：创建请求立即返回 `data.task_id`，随后轮询查询接口。
- 同步（`sync=1`）：创建请求等待处理完成，并直接返回任务结果。
## 图片来源
`image_file`、`image_url`、`image_base64` 三者必选其一；同时传入时优先级为 `image_file > image_url > image_base64`。
## 接口列表
| 用途 | 请求方式 | 路径 |
| --- | --- | --- |
| 创建图片黑白化任务 | POST | /api/tasks/visual/grayscale-conversion |
| 查询任务结果（异步） | GET | /api/tasks/visual/grayscale-conversion/{task_id} |
## 创建图片黑白化任务
`POST /api/tasks/visual/grayscale-conversion`
Content-Type: `multipart/form-data`
### 请求参数
| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| image_file | file | 三者必选其一 | 图片文件。支持 jpg、jpeg、bmp、png、webp、tiff、bitmap；最高优先级。服务端接收到的文件最大不超过 20MB（含 20MB）。 |
| image_url | string | 三者必选其一 | 图片下载地址。支持 HTTP 和 OSS 协议，最长 512 个字符，下载超时 20 秒；优先级低于 image_file、高于 image_base64。 |
| image_base64 | string | 三者必选其一 | 图片的 base64 编码；数据量会增加约 33%，不推荐使用。 |
| sync | integer | 可选 | 是否同步返回。1 = 同步；0 = 异步（默认）。 |
| type | string | 可选 | 前景类型。不填时自动识别（默认）；可选 person、object、stamp。 |
| gray_strength | string | 可选 | 灰度强度，范围为 1～10，默认值为 5；值越小效果越暗，值越大效果越亮。 |
### 返回参数 - 异步（sync=0）
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | integer | HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败。 |
| message | string | 接口返回消息。任务失败时可携带该消息联系商务或技术支持。 |
| data.task_id | string | 任务 ID，用于后续查询黑白化结果。 |
### 返回参数 - 同步（sync=1）
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | integer | HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败。 |
| message | string | 接口返回消息。任务失败时可携带该消息联系商务或技术支持。 |
| data.task_id | string | 任务 ID。任务失败时，可携带该参数联系商务或技术支持。 |
| data.created_at | integer | 任务创建时间戳。 |
| data.processed_at | integer | 任务开始被处理的时间戳。 |
| data.completed_at | integer | 任务完成时间戳。 |
| data.image | string | 黑白化结果图片下载 URL 或 base64 数据；URL 有效期一般为 1 小时。 |
| data.gray_strength | integer | 模糊程度。 |
| data.progress | integer | 任务处理进度，范围为 0～100；100 表示处理完成。 |
| data.state | integer | 任务状态码。1 表示成功，大于 1 表示处理中，小于 0 表示失败。 |
| data.result_type | string | 服务实际识别的黑白化类型：person、object 或 stamp。 |
| data.type | string | 请求指定的黑白化类型；auto 表示自动识别。 |
| data.time_elapsed | string | 任务处理耗时。 |
| data.use_point | integer | 扣费点数。 |
| data.output_type | integer | 选择的图片返回结果类型。 |
| data.return_type | integer | 结果返回方式。 |
### cURL 示例
异步，使用图片 URL：
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/grayscale-conversion' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'image_url=YOUR_IMAGE_URL' \
-F 'gray_strength=5'
```
异步，上传本地文件：
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/grayscale-conversion' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'image_file=@/path/to/image.jpg' \
-F 'gray_strength=5'
```
同步，直接返回结果：
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/grayscale-conversion' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_url=YOUR_IMAGE_URL' \
-F 'gray_strength=5'
```
## 查询图片黑白化结果
异步请求建议每 **1 秒**轮询一次结果，最大轮询时长为 **300 秒**。当 `data.state=1` 或 `data.state<0` 时停止轮询。
`GET /api/tasks/visual/grayscale-conversion/{task_id}`
### 路径参数
| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| task_id | string | 必填 | 创建异步黑白化任务后返回的任务 ID。 |
### 返回参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | integer | HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败。 |
| message | string | 接口返回消息。任务失败时可携带该消息联系商务或技术支持。 |
| data.task_id | string | 任务 ID。任务失败时，可携带该参数联系商务或技术支持。 |
| data.created_at | integer | 任务创建时间戳。 |
| data.processed_at | integer | 任务开始被处理的时间戳。 |
| data.completed_at | integer | 任务完成时间戳。 |
| data.image | string | 黑白化结果图片下载 URL 或 base64 数据；URL 有效期一般为 1 小时。 |
| data.gray_strength | integer | 模糊程度。 |
| data.progress | integer | 任务处理进度，范围为 0～100；100 表示处理完成。 |
| data.state | integer | 任务状态码。1 表示成功，大于 1 表示处理中，小于 0 表示失败。 |
| data.result_type | string | 服务实际识别的黑白化类型：person、object 或 stamp。 |
| data.type | string | 请求指定的黑白化类型；auto 表示自动识别。 |
| data.time_elapsed | string | 任务处理耗时。 |
| data.use_point | integer | 扣费点数。 |
### cURL 示例
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/grayscale-conversion/{task_id}' \
-H 'X-API-KEY: YOUR_API_KEY'
```
## 推荐异步流程
1. 使用 `sync=0` 和一种图片来源 POST 到 `/api/tasks/visual/grayscale-conversion`，读取 `data.task_id`。
2. 每隔 1 秒 GET `/api/tasks/visual/grayscale-conversion/{task_id}`，累计轮询时间不要超过 300 秒。
3. 检查 `data.state`：1 = 完成；大于 1 = 继续轮询；小于 0 = 失败。
4. 在 1 小时内下载 `data.image`。
## 使用规范与限制
1. 接口返回的结果图片链接一般有效期为 1 小时，请及时下载并存储。
2. HTTP status 为 200 仅表示 HTTP 请求成功，并不表示图片黑白化成功；请结合 `data.state` 判断任务结果。
3. 使用 URL 作为参数时，请遵守 URL 编码规范，避免参数解析混乱。
4. 每次成功调用消耗 15 点。
5. 上传图片需符合以下格式、分辨率和大小限制。
| 格式 | 分辨率 | 大小 |
| --- | --- | --- |
| jpg, jpeg, bmp, png, webp, tiff, bitmap | 最大 4096x4096 | 最大 20MB |
## 状态码
任务是否成功，需要结合 HTTP 响应状态码（`status`）和任务状态码（`data.state`）共同判断。
### HTTP 响应状态码
| 状态码 | 说明 |
| --- | --- |
| 200 | 请求成功。 |
| 400 | 客户端参数传递错误，请检查参数是否缺失或值是否正确。 |
| 401 | 认证失败，请检查 X-API-KEY 是否正确或服务是否开通。 |
| 404 | 请求的 URL 或资源不存在，请检查 URL 或 task_id。 |
| 413 | 上传文件超出大小限制。 |
| 429 | 请求频率超出 QPS 限制（默认 QPS 为 2）。 |
| 500 | 服务端异常，请联系商务或技术支持。 |
### 任务状态码（data.state）
| 状态码 | 说明 |
| --- | --- |
| -8 | 处理超时，最长处理时间 5 分钟。 |
| -7 | 无效图片文件，如文件损坏或格式不正确。 |
| -5 | 图片超出 20MB 大小限制。 |
| -3 | 服务器下载图片失败，请检查图片 URL。 |
| -2 | 黑白化完成，但上传 OSS 失败。 |
| -1 | 黑白化失败。 |
| 0 | 排队中。 |
| 1 | 完成，黑白化成功。 |
| 2 | 准备中。 |
| 3 | 等待中。 |
| 4 | 处理中。 |