适用场景与接口能力
在登录页、桌面壁纸应用、文章封面图或小程序首页轮播等场景中，随机壁纸是一个高频需求。本接口对接 360 公开壁纸库，提供 16 个分类 × 7 种分辨率（含 1920×1080 原图）的随机壁纸，QPS 为 20/s，足以应对中小型业务场景。
接口 URL：https://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（注意横线） | 1920x1080 |
count | 否 | number | 返回壁纸数量，1–20 | 1 |
参数名严格小写，分辨率的乘号用小写字母
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=动漫&resolution=1920x1080&count=1"将输出一个 JSON 对象，包含图片数据。只需替换APIZERO_API_KEY即可运行，无需安装任何依赖。
代码接入示例
Python（使用 requests）
import 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, params=params, headers=headers) if resp.status_code == 200: data = resp.json() for img in data["data"]["images"]: print(img["url"]) # 直接输出可用的 HTTPS 图片链接JavaScript（浏览器 fetch）
const 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（可读标签数组）、url（HTTPS 图片链接）。注意tag_text是标签的原始空格分隔字符串，推荐优先使用tags数组。data.category_id：分类内部 ID，可作缓存键之一。request_id：本次请求的唯一标识，方便排查问题。
常见错误与排查
| HTTP 状态码 | 可能原因 | 排查要点 |
|---|---|---|
| 401 | API Key 缺失或无效 | 检查请求头X-API-Key是否正确传递 |
| 400 | 参数格式错误 | 确认category是否为支持的中文名，resolution是否使用小写x |
| 429 | 请求频率超限 | 当前 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 文档
