一、适用场景与接口能力边界AI图片变清晰接口基于超分辨率算法输入一张公网可访问的模糊/低分辨率图片URL约4~6秒复杂图片可能10~30秒输出4倍放大的高清JPEG图片。典型使用场景包括老照片修复、电商商品图增强、截图放大、素材预处理等。能力边界输入格式JPEG / PNG / WebP / BMP文件大小≤ 10 MB图片URL必须是公网可访问的http/https链接私有OSS需先签名输出有效期返回的enhanced_url在6小时内有效需尽快下载QPS限制1次/秒超出会返回429 Too Many Requests二、鉴权与请求参数Header参数参数名是否必填类型说明Authorization是stringAPI Key在控制台申请示例中为X-API-Key实际以文档为准Content-Type否string默认application/json也可使用application/x-www-form-urlencoded请求体JSON{ img: https://example.com/blurry-photo.jpg }img必填待增强的图片URL字符串类型。三、curl 接入示例以下为可复制的完整请求请将$APIZERO_API_KEY替换为真实密钥curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {img: https://example.com/blurry-photo.jpg} \ https://v1.apizero.cn/api/image-enhance若使用application/x-www-form-urlencodedcurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -d imghttps://example.com/blurry-photo.jpg \ https://v1.apizero.cn/api/image-enhance四、响应字段解读成功响应HTTP 200{ code: 0, msg: 成功, request_id: mqx8x12345abc, data: { original_url: https://example.com/blurry-photo.jpg, enhanced_url: https://v1.apizero.cn/api/image-enhance?modeimageuaHR0cHM6Ly9...sa1b2c3d4e5f6, width: 1200, height: 1200, expires_in: 21600 } }字段类型说明codeint0表示成功非0表示业务错误见下文msgstring提示信息request_idstring请求唯一标识用于排查data.original_urlstring原图URLdata.enhanced_urlstring增强后图片临时访问地址有效期6小时data.widthint输出图片宽度像素data.heightint输出图片高度像素data.expires_inint有效剩余秒数五、常见错误与排查路径5.1 HTTP 400 Bad Request触发原因请求体JSON格式错误、img参数缺失、URL格式不合法非http/https、图片格式不支持。示例响应{ code: 40001, msg: 参数校验失败img字段必须为有效的http/https URL }排查步骤检查请求体是否为合法JSON可使用jq .验证。确认img值以http://或https://开头。确认图片扩展名在JPEG/PNG/WebP/BMP范围内不区分大小写。若使用form-urlencoded确保已正确编码特殊字符。5.2 HTTP 401 Unauthorized触发原因未提供Authorization头、API Key无效或已过期。排查步骤确认Header名、大小写是否与文档一致如X-API-Key或Authorization以实际文档为准。在控制台重新生成并替换API Key。检查是否有空格或换行符混入Key值。5.3 HTTP 403 Forbidden触发原因API Key被停用、账户余额不足针对付费模式或被服务端风控拦截如IP/请求频率异常。排查步骤登录控制台确认账户状态。如果使用每日调用次数限制检查是否已耗尽超出后需充值。避免频繁请求QPS限制1次/秒必要时增加重试间隔。确认请求IP未被服务端限制。5.4 HTTP 413 Payload Too Large触发原因图片文件超过10 MB限制注意是文件大小不是URL长度。排查步骤使用curl -I或wget --spider获取图片的Content-Length头。若超过10MB需压缩或使用更小尺寸的原图。注意某些CDN/存储桶返回的Content-Length可能不准确建议直接下载后检查。5.5 HTTP 429 Too Many Requests触发原因请求频率超过QPS限制1次/秒。排查步骤在并发场景下使用队列或限流如令牌桶。每次请求后至少等待1秒再发起下一次。如果批量处理大量图片考虑分批次、加延迟。5.6 HTTP 500 Internal Server Error 或 502/503触发原因服务端临时故障或超载也可能是输入图片内容异常如损坏、分辨率极低导致处理进程崩溃。排查步骤记录request_id稍后重试建议指数退避。检查原图是否可正常访问且非损坏文件例如使用浏览器打开确认。如果持续返回5xx联系技术支持并提供request_id。5.7 业务错误码code非0除了HTTP状态码响应体中的code字段也可能返回非0值code: 50001—— 图片下载失败原图URL不可达或超时code: 50002—— 图片格式解析失败文件损坏或非标准格式code: 50003—— AI处理超时复杂图片超过默认时间可尝试分批或降低分辨率排查步骤先用wget或curl测试原图URL能否正常下载。确认图片文件头部符合格式规范如JPEG以FF D8 FF开头。若原图尺寸过大如10000×10000建议先缩小到常用尺寸再调用。六、工程化注意事项6.1 错误重试策略对429和5xx错误采用指数退避重试第一次等待2秒第二次4秒第三次8秒最多3次。对4xx错误除429不重试直接记录日志并报警。对业务错误码50001~50003可根据场景选择换图或提示用户。6.2 资源管理如果同时发起多张图片增强需保证请求间隔≥1秒建议用Promise.all配合setTimeout控制。6.3 监控与日志打印每次请求的request_id、HTTP状态、响应耗时。监控code字段对非0值发出告警。统计图片增强前后的文件大小防止异常放大导致存储维护复杂度激增。6.4 安全建议API Key不要硬编码在客户端代码中应放在后端环境变量。用户传入的图片URL需做域名白名单校验避免SSRF攻击。七、参考文档API文档https://apizero.cn/aidocs/image-enhance原始技术说明https://apizero.cn/aidocs/image-enhance/raw.md