随机壁纸是一个很小的生活服务类接口作用是返回指定分类和分辨率下的随机壁纸图片 URL。它的请求路径、参数和响应结构都很简单适合作为 API 调试技巧的入门样例。这篇文章不讨论复杂的架构只解决一个问题如何用一条可运行的请求拿到一张可用的图片链接。接口概览与适用场景该接口对接 360 公开壁纸库上游提供了 16 个分类和 7 种分辨率。接口内部按分类和分辨率对上游响应做缓存本地再执行随机 shuffle因此每次请求返回的图片集合不同但上游请求量并不会随调用次数线性增长。典型的应用场景包括登录页背景每次刷新页面展示不同的风景或动漫壁纸。桌面壁纸小工具定时请求接口更换本机桌面。文章封面图按文章主题选择分类自动配一张图。小程序首页轮播用 count 参数一次取多张交给前端轮播组件。如果你只是做功能验证最快的方式就是直接用 curl 请求一次看返回结构是否满足预期。请求地址与能力边界基础信息接口名称随机壁纸slugwallpaper请求方法GET请求地址https://v1.apizero.cn/api/wallpaper分类生活服务QPS20 / s文档页https://apizero.cn/aidocs/wallpaper这里需要明确一个边界QPS 20 / s 指的是单个 API Key 的调用频率上限不是接口的并发容量。在实际开发中即使你的业务量很小也应该在前端做节流或缓存不要每次渲染都直接打接口。Query 参数说明参数名必填类型说明默认值可选值category否string壁纸分类中文名风景16 个分类见下表resolution否string目标分辨率1920x10807 种分辨率见下表count否number返回图片数量11-2016 个分类美女、风景、游戏、影视、时尚、明星、汽车、萌宠、清新、体育、萌娃、军事、动漫、日历、爱情、格言。7 种分辨率分辨率说明1920x1080原图1600x900宽屏1440x900宽屏1366x768笔记本常见尺寸1280x800宽屏1280x1024方屏1024x768普屏一个容易忽略的点是 URL 中的分辨率参数用的是字母x不是星号*也不是全角乘号。例如1920x1080是正确的1920*1080会被当成非法参数。鉴权方式请求需要携带 API Key通过 HTTP 头X-API-Key传递。在命令行中可以通过环境变量注入export APIZERO_API_KEYyour-key-here然后在 curl 请求中使用$APIZERO_API_KEY引用。注意不要直接把 Key 写到代码仓库里尤其是前后端共享的仓库。curl 最小可运行示例以下示例按照 API 文档提供的请求方式编写返回风景分类、1920x1080 分辨率的两张随机壁纸curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/wallpaper?category风景resolution1920x1080count2如果你还没有配置环境变量可以直接把$APIZERO_API_KEY替换为实际 Keycurl -sS \ -X GET \ -H X-API-Key: 你的APIKey \ https://v1.apizero.cn/api/wallpaper?category风景resolution1920x1080count2-sS的含义是静默模式但不隐藏错误。去掉-s会显示请求进度信息不适合脚本化调用去掉-S则可能在连接失败时没有任何报错输出不利于排查。执行成功后你会得到一个 JSON 数组数组内只有一个元素元素中的example字段就是完整的响应体。使用 jq 快速验证返回结构如果本机安装了 jq可以配合 curl 直接提取图片 URLcurl -sS \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/wallpaper?category风景resolution1920x1080count2 \ | jq -r .[0].example.data.images[].url这条命令的输出是两张图片的完整 URL 列表可以直接拼接到 curl 之后下载图片curl -sS -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/wallpaper?category风景resolution1920x1080count1 \ | jq -r .[0].example.data.images[0].url \ | xargs curl -sS -o wallpaper.jpg注意xargs curl只适用于 URL 中不包含特殊空格的场景如果 URL 中包含特殊字符建议用while read逐行处理。JavaScript 接入示例以浏览器环境为例使用 fetch 发起请求const API_KEY your-api-key; const url new URL(https://v1.apizero.cn/api/wallpaper); url.searchParams.set(category, 风景); url.searchParams.set(resolution, 1920x1080); url.searchParams.set(count, 1); const response await fetch(url, { headers: { X-API-Key: API_KEY } }); const payload await response.json(); const wrapper payload[0]; if (wrapper.example.code ! 0) { throw new Error(wrapper.example.msg); } const image wrapper.example.data.images[0]; console.log(image.url);在 Node.js 18 中这段代码可以直接以.mjs文件运行。注意fetch的默认行为不会自动解码中文 URL 参数URLSearchParams会做正确编码不要手动拼接 query string。Python 接入示例使用urllib.request标准库不依赖第三方包import json import urllib.parse import urllib.request API_KEY your-api-key params urllib.parse.urlencode({ category: 风景, resolution: 1920x1080, count: 2, }) url fhttps://v1.apizero.cn/api/wallpaper?{params} req urllib.request.Request(url, headers{ X-API-Key: API_KEY, }) with urllib.request.urlopen(req, timeout10) as resp: payload json.loads(resp.read().decode(utf-8)) wrapper payload[0] if wrapper[example][code] ! 0: raise RuntimeError(wrapper[example][msg]) for img in wrapper[example][data][images]: print(img[url])这里把超时时间设置为 10 秒。壁纸图片 URL 指向 360 图床下载图片时建议单独设置更长的超时时间不要把「拿接口数据」和「下载图片」放在同一个超时控制里。返回字段解读响应是一个 JSON 数组数组内每个元素描述一个响应状态。实际业务数据在example字段中。以count2的请求为例核心结构如下{ code: 0, data: { category: 风景, category_id: 9, count: 2, images: [ { id: 2054209, resolution: 1920x1080, tag_text: 海洋天堂 日出东方 松树 海岛, tags: [海洋天堂, 日出东方, 松树, 海岛], url: https://p2.qhimg.com/bdr/__85/t019ca75cd449be50c1.jpg } ], requested: 2, resolution: 1920x1080 }, msg: 成功, request_id: abc123def456 }字段说明字段类型说明codenumber状态码0 表示成功msgstring描述信息request_idstring单次请求的标识用于排查问题data.categorystring实际返回的分类名data.category_idnumber分类内部 IDdata.countnumber实际返回的图片数量data.requestednumber请求时传入的 count 值data.resolutionstring实际返回的分辨率data.imagesarray图片列表images[].idnumber图片 IDimages[].resolutionstring图片分辨率images[].tag_textstring图片标签的文本拼接形式images[].tagsarray图片标签数组便于程序化处理images[].urlstring图片完整下载地址其中requested和count的含义不同requested是你要求返回的数据量count是实际返回的数据量。在正常状态下两者相等如果上游图片不足count会小于requested但接口仍然返回code0。这也是一个容易误判的点。关于返回内容的两个工程细节tags数组来自上游内部标记的拆分处理。例如tag_text是海洋天堂 日出东方 松树 海岛tags就是[海洋天堂, 日出东方, 松树, 海岛]。如果你的业务需要对图片做标签筛选直接使用tags数组即可不需要再按空格切分。接口内部已把上游的http://图片地址强制改写为https://。这避免了在 HTTPS 页面中因加载 HTTP 图片而产生混合内容警告。你拿到的url字段可以直接用于img标签。图片 URL 的使用方式拿到url后前端可以直接渲染img srchttps://p2.qhimg.com/bdr/__85/t019ca75cd449be50c1.jpg alt随机壁纸 /后端可以将 URL 持久化到数据库也可以直接做图片代理下载import urllib.request img_url https://p2.qhimg.com/bdr/__85/t019ca75cd449be50c1.jpg urllib.request.urlretrieve(img_url, wallpaper.jpg)需要注意的是图片 URL 的域名是p2.qhimg.com不是 API 域名。如果你的服务器需要配置白名单需要把图片域名一并加入。常见错误与排查1. HTTP 401 Unauthorized原因通常是X-API-Key没有正确传递。检查环境变量是否已导出echo $APIZERO_API_KEY如果输出为空说明没有设置环境变量或者设置到了不同的 shell 进程。2. HTTP 400 Bad Request原因通常是 category 或 resolution 参数值不在可选范围内。例如把1920x1080写成1920*1080或者把分类写成英文fengjing都会导致参数校验失败。3. 返回 code 非 0响应外层的 HTTP 状态可能是 200但code字段不为 0。此时业务逻辑不应该继续处理图片列表而是抛出异常。建议把code ! 0视为业务层错误。4. count 返回数量小于请求值如前面所述requested和count不一致时应使用count作为实际遍历的上限避免访问不存在的images[i]。5. 连接超时或 SSL 证书错误在容器或服务器环境中检查系统时间和 CA 证书是否正常。开发者可以在代码中显式设置超时时间例如 Python 的urlopen(..., timeout10)避免进程长时间阻塞。工程化注意事项1. 不要在每次请求时都动态拼接中文参数建议将分类和分辨率定义为常量。尤其在前端代码中硬编码中文关键词容易导致 URL 编码问题。2. 对图片 URL 做缓存而不是只缓存接口响应接口本身已做了 1 小时的上游缓存但你的应用层仍需考虑图片 URL 的重复利用。如果一个用户刷新页面 10 次每次都拿到相同的 URL 集合直接展示缓存即可不需要重复请求接口。3. 控制请求频率接口 QPS 上限为 20 / s这不算高。在多人共用同一 API Key 的场景下建议在网关层做限流或者把图片 URL 聚合后通过自己的接口下发。4. 考虑图片域名隔离前端页面加载图片时浏览器对p2.qhimg.com的并发连接数可能受限。如果一次展示多张壁纸建议设置loadinglazy。5. 不要把 API Key 暴露给前端浏览器环境下X-API-Key可以被用户看到。最佳做法是后端请求该接口前端再从自己的服务端获取图片数据。6. 增加维度校验检查images[].resolution是否真的等于请求参数。虽然接口文档承诺会按参数返回对应分辨率但作为上游对接方保留一层校验能降低图片尺寸不符的风险。小结随机壁纸接口的最小可运行流程可以概括为三步构造 GET 请求地址带上category、resolution、count三个可选参数。在 HTTP 头中传入X-API-Key。解析返回数组中的example.data.images取出url字段。整个调试过程不需要复杂的客户端或依赖库curl jq 即可完成链路验证。对于需要嵌入业务系统的开发者可以直接参考 JavaScript 或 Python 的接入片段并在工程化层面重视缓存、超时、参数校验三项基础问题。参考文档接口文档https://apizero.cn/aidocs/wallpaper原始文档https://apizero.cn/aidocs/wallpaper/raw.md