图片高级变清晰API

免费体验

AI 使用更高质量的模型提升图片清晰度，增强图像细节和分辨率。适用于商品图、人像照片、设计素材等场景。支持异步、同步两种调用方式。

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

鉴权

每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。

X-API-KEY: YOUR_API_KEY

创建图片高级变清晰任务

POST /api/tasks/visual/scale-pro

请求参数

image_url string 可选

原图下载地址。支持 HTTP 协议和 OSS 协议，最长 512 个字符，下载超时 10 秒。如果同时传入 image_url 与 image_file，优先使用 image_file。

二选一必填

image_file file 可选

原图文件（二进制）。支持格式：jpg、jpeg、bmp、png、webp、tiff、bitmap。如果同时传入 image_file 与 image_url，优先使用 image_file。输入图片大小最大不超过 30MB，最大分辨率 4096x4096。

图片上传要求请参看使用规范与限制#6。

sync integer 可选

是否同步返回。0 表示异步；1 表示同步。

type integer 可选

类型。0 表示超清，消耗 5 算粒；1 表示高清，消耗 4 算粒。默认值为 0。

return_type integer 可选

结果返回方式。1 表示返回图片下载地址；2 表示返回 base64 字符串。默认值为 1。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

返回信息说明。若失败，可参考该信息定位问题。

data.task_id string

图片高级变清晰任务 ID，用于轮询结果。

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

返回信息说明。若处理失败，可参考该信息定位问题。

data.task_id string

图片高级变清晰任务 ID。

data.created_at number

任务创建时间戳。

data.processed_at number

任务开始处理时间戳。

data.completed_at number

任务完成时间戳。

data.image string

结果图片下载地址或 base64 数据，链接有效期为 1 小时。

data.return_type number

结果返回方式。

data.type number

调用的模型类型。

data.progress number

任务处理进度，取值范围 0~100。

data.state number

任务状态码。1 表示处理成功，大于 1 表示处理中，小于 0 表示失败，详见状态码说明。

data.image_width number

输出图片宽度。

data.image_height number

输出图片高度。

data.image_size_kb number

输出图片大小，单位 KB。

data.out_format string

输出图片格式。

data.state_detail string

状态详情。

data.download_time number

下载耗时。

data.time_elapsed number

任务耗时。

查询图片高级变清晰结果

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

GET /api/tasks/visual/scale-pro/{task_id}

路径参数

task_id string 必填

创建任务接口返回的 task_id，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

返回信息说明。若处理失败，可参考该信息定位问题。

data.task_id string

图片高级变清晰任务 ID。任务失败时，可携带该参数联系商务或技术支持。

data.created_at number

任务创建时间戳。

data.processed_at number

任务开始处理时间戳。

data.completed_at number

任务完成时间戳。

data.image string

结果图片下载地址或 base64 数据，链接有效期为 1 小时。

data.return_type number

结果返回方式。

data.type number

调用的模型类型。

data.progress number

任务处理进度，取值范围 0~100。

data.state number

任务状态码。1 表示处理成功，大于 1 表示处理中，小于 0 表示失败，详见状态码说明。

data.image_width number

输出图片宽度。

data.image_height number

输出图片高度。

data.image_size_kb number

输出图片大小，单位 KB。

data.out_format string

输出图片格式。

data.state_detail string

状态详情。

data.download_time number

下载耗时。

data.time_elapsed number

任务耗时。

使用规范与限制

接口返回的链接有效期为 1 小时，请及时下载存储。
HTTP status 为 200 表示 HTTP 请求成功，并非图片高级变清晰处理成功，任务结果请结合 data.state 判断，详见状态码说明。
使用 URL 传参时，请按照 URL 编码规范处理，避免参数解析异常。
type=0 消耗 5 算粒；type=1 消耗 4 算粒。
输出图像与输入图像保持相同的宽高比；输入图片长边 ≤ 256 像素时，输出图片像素面积（宽×高）不超过 1024×1024 像素；输入图片长边 > 256 像素时，输出图片像素面积（宽×高）不超过 2048×2048 像素。
上传图片需符合以下格式、分辨率和大小限制。

格式分辨率大小

jpg, jpeg, bmp, png, webp, tiff, bitmap 最大 4096x4096 最大30MB

格式	分辨率	大小
jpg, jpeg, bmp, png, webp, tiff, bitmap	最大 4096x4096	最大30MB

响应

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": 1776318296, // 仅在异步轮询结果中存在。
    "processed_at": 1776318296, // 仅在异步轮询结果中存在。
    "completed_at": 1776318305, // 仅在异步轮询结果中存在。
    "image": "https://wxtechsz.oss-cn-shenzhen.aliyuncs.com/tasks/output/scale_pro/a065673f-6f1f-41dc-9719-50cf7699d9d8.jpg", // 仅在异步轮询结果中存在。
    "return_type": 1, // 仅在异步轮询结果中存在。
    "type": 0, // 仅在异步轮询结果中存在。
    "progress": 100, // 仅在异步轮询结果中存在。
    "state": 1, // 仅在异步轮询结果中存在。
    "image_width": 0, // 仅在异步轮询结果中存在。
    "image_height": 0, // 仅在异步轮询结果中存在。
    "image_size_kb": 2523, // 仅在异步轮询结果中存在。
    "out_format": "jpg", // 仅在异步轮询结果中存在。
    "state_detail": "Complete", // 仅在异步轮询结果中存在。
    "download_time": 0, // 仅在异步轮询结果中存在。
    "time_elapsed": 0 // 仅在异步轮询结果中存在。
  }
}