适用场景与接口能力在登录页、桌面壁纸应用、文章封面图或小程序首页轮播等场景中随机壁纸是一个高频需求。本接口对接 360 公开壁纸库提供 16 个分类 × 7 种分辨率含 1920×1080 原图的随机壁纸QPS 为 20/s足以应对中小型业务场景。接口 URLhttps://v1.apizero.cn/api/wallpaper请求方法GET能力边界16 个分类美女 / 风景 / 游戏 / 影视 / 时尚 / 明星 / 汽车 / 萌宠 / 清新 / 体育 / 萌娃 / 军事 / 动漫 / 日历 / 爱情 / 格言。不传参数时默认返回「风景」。7 种分辨率1920×1080原图、1600×900、1440×900、1366×768、1280×800、1280×1024、1024×768。默认 1920×1080。返回数量1–20 张默认 1。缓存优化上游响应按(category_id, start_bucket)缓存 1 小时shuffle 在本地完成实际请求可节省约 80% 的上游调用同时保持随机性。数据修复原上游代码存在两个 BUG分辨率映射缺失、tag 不可读、图片 http 链接接口已统一修复返回的tags数组为可读标签url强制为 HTTPS。请求参数与鉴权调用此接口需携带 API Key通过 HTTP HeaderX-API-Key传递。参数全部通过 Query String 设置参数必需类型说明默认值category否string分类中文名16 选 1风景resolution否string分辨率7 选 1注意横线1920x1080count否number返回壁纸数量1–201参数名严格小写分辨率的乘号用小写字母x分隔如1920x1080。curl 最小可运行示例以下 curl 命令请求一张「动漫」分类、1920×1080 的随机壁纸export APIZERO_API_KEY你的密钥 curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/wallpaper?category动漫resolution1920x1080count1将输出一个 JSON 对象包含图片数据。只需替换APIZERO_API_KEY即可运行无需安装任何依赖。代码接入示例Python使用 requestsimport requests api_key 你的密钥 url https://v1.apizero.cn/api/wallpaper params { category: 风景, resolution: 1920x1080, count: 3 } headers {X-API-Key: api_key} resp requests.get(url, paramsparams, headersheaders) if resp.status_code 200: data resp.json() for img in data[data][images]: print(img[url]) # 直接输出可用的 HTTPS 图片链接JavaScript浏览器 fetchconst apiKey 你的密钥; const params new URLSearchParams({ category: 萌宠, resolution: 1920x1080, count: 1 }); fetch(https://v1.apizero.cn/api/wallpaper?${params}, { headers: { X-API-Key: apiKey } }) .then(res res.json()) .then(json { const imgUrl json.data.images[0].url; // 将 imgUrl 设置为页面背景图 document.body.style.backgroundImage url(${imgUrl}); });两个示例均无外部依赖Python 需pip install requests可直接复制使用。返回值解读成功响应HTTP 200{ code: 0, msg: 成功, request_id: abc123def456, data: { category: 风景, category_id: 9, count: 2, resolution: 1920x1080, requested: 2, images: [ { id: 2054209, resolution: 1920x1080, tag_text: 海洋天堂 日出东方 松树 海岛, tags: [海洋天堂, 日出东方, 松树, 海岛], url: https://p2.qhimg.com/bdr/__85/t019ca75cd449be50c1.jpg } ] } }关键字段说明code业务状态码0 表示成功。data.images图片数组每项包含id唯一标识、resolution实际分辨率、tags可读标签数组、urlHTTPS 图片链接。注意tag_text是标签的原始空格分隔字符串推荐优先使用tags数组。data.category_id分类内部 ID可作缓存键之一。request_id本次请求的唯一标识方便排查问题。常见错误与排查HTTP 状态码可能原因排查要点401API Key 缺失或无效检查请求头X-API-Key是否正确传递400参数格式错误确认category是否为支持的中文名resolution是否使用小写x429请求频率超限当前 QPS 限制 20/s可增加客户端节流或使用count一次获取多张减少调用500上游服务异常稍后重试若持续可查看官方文档更新另外返回的code字段不为 0 时需根据msg字段处理业务逻辑。工程化注意事项图片 URL 的稳定性返回的url来自 360 图床有效期较长但非永久。建议客户端做 404 兜底如显示占位图。减少重复请求利用接口自带的缓存机制1 小时相同 category resolution 的请求会走缓存。若需频繁切换可客户端再缓存 5–10 分钟。分辨率选择移动端可选用1024x768或1280x800减小图片体积桌面端推荐1920x1080原图。注意分辨率参数名不要加空格。HTTPS 强制接口已处理上游的 http 链接返回均为 HTTPS无需额外转换。错误重试建议指数退避重试如 1s、2s、4s单次失败不影响用户体验。参考文档随机壁纸 API 官方文档原始 Markdown 文档