<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 随机壁纸

> 对接 360 公开壁纸库，16 个分类 × 7 种分辨率（含 1920×1080 原图）随机壁纸。

• **16 个分类**：美女 / 风景 / 游戏 / 影视 / 时尚 / 明星 / 汽车 / 萌宠 / 清新 / 体育 / 萌娃 / 军事 / 动漫 / 日历 / 爱情 / 格言
• **7 种分辨率**：1920×1080（原图）/ 1600×900 / 1440×900 / 1366×768 / 1280×800 / 1280×1024 / 1024×768
• **修复源码 BUG**：源码注释默认 1920×1080 但代码默认 1600×900 且 resMap 缺 1920×1080 → 现已用上游 url 字段返回真正 1920×1080 原图
• **修复源码 BUG**：源码 tag 字段返回内部标记（如 `_category_海洋天堂_`）不可读 → 现已拆分 utag 输出为 tags 数组（如 `['海洋天堂','日出东方','松树','海岛']`）
• **修复源码 BUG**：上游图片 URL 是 http:// → 现已强制改写为 https://，避免 HTTPS 站点混合内容警告
• **缓存优化**：上游响应按 (cid, start_bucket) 缓存 1h，shuffle 在本地做，**节省 80% 上游请求同时保证随机性**
• **典型场景**：登录页背景 / 桌面壁纸应用 / 文章封面图 / 小程序首页轮播

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `wallpaper` |
| 接口名称 | 随机壁纸 |
| 接口地址 | `https://v1.apizero.cn/api/wallpaper` |
| 请求方法 | `GET` |
| 分类 | life |
| 提供方 | 360 壁纸 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 20 req/s |
| 每日免费额度 | 1000 次（已认证用户） |
| 匿名每日额度 | 200 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 200 次、QPS 10；登录用户每日 1000 次、QPS 20（全部免费）。上游响应缓存 1h，命中不计入上游配额。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `category` | `string` | 否 | 分类中文名，可选：美女 / 风景 / 游戏 / 影视 / 时尚 / 明星 / 汽车 / 萌宠 / 清新 / 体育 / 萌娃 / 军事 / 动漫 / 日历 / 爱情 / 格言。默认「风景」 | `风景` |
| `resolution` | `string` | 否 | 分辨率，可选：1920x1080（原图）/ 1600x900 / 1440x900 / 1366x768 / 1280x800 / 1280x1024 / 1024x768。默认 1920x1080 | `1920x1080` |
| `count` | `int` | 否 | 返回数量，1-20。默认 1 | `5` |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/wallpaper?category=%E9%A3%8E%E6%99%AF&resolution=1920x1080&count=5&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `category` | `string` | 回传分类中文名 | — |
| `category_id` | `number` | 360 内部分类 ID（cid） | — |
| `resolution` | `string` | 回传分辨率 | — |
| `count` | `number` | 实际返回的图片数量（可能少于 requested 当上游存量不足） | — |
| `requested` | `number` | 客户端请求的数量 | — |
| `images` | `array` | 壁纸图片数组 | — |
| `images[].url` | `string` | 图片 URL（已强制 HTTPS，可直接用于 <img src=>） | — |
| `images[].id` | `number` | 360 壁纸 ID（用于唯一标识） | — |
| `images[].resolution` | `string` | 该图片分辨率（与请求一致） | — |
| `images[].tags` | `array` | 标签数组（拆分自 utag）：如 ["海洋天堂","日出东方","松树","海岛"] | — |
| `images[].tag_text` | `string` | 原始标签文本（空格分隔）：如 "海洋天堂 日出东方 松树 海岛" | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "category": "风景",
        "category_id": 9,
        "resolution": "1920x1080",
        "count": 2,
        "requested": 2,
        "images": [
            {
                "url": "https:\/\/p2.qhimg.com\/bdr\/__85\/t019ca75cd449be50c1.jpg",
                "id": 2054209,
                "resolution": "1920x1080",
                "tags": [
                    "海洋天堂",
                    "日出东方",
                    "松树",
                    "海岛"
                ],
                "tag_text": "海洋天堂 日出东方 松树 海岛"
            },
            {
                "url": "https:\/\/p2.qhimg.com\/bdr\/__85\/t021abc.jpg",
                "id": 2054210,
                "resolution": "1920x1080",
                "tags": [
                    "雪山",
                    "日出",
                    "云海"
                ],
                "tag_text": "雪山 日出 云海"
            }
        ]
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：不支持的分类 / 不支持的分辨率 / count 不在 1-20 之间 |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | 上游 HTTP 失败 |
| `5021` | `—` | 上游响应格式异常 / 该分辨率下无可用壁纸 |

## 9. 变更日志

- **1.0.0** (2026-05-07)
  - 首次上线，对接 360 壁纸库 16 分类 × 7 分辨率
  - 修复源码 BUG：默认分辨率从「1600×900」改为真正的 1920×1080 原图（用上游 url 字段）
  - 修复源码 BUG：tag 字段从内部标记（_category_xxx_）改为可读 utag 拆分数组
  - 修复源码 BUG：图片 URL 强制改写 http:// → https://，避免 HTTPS 站点混合内容警告
  - 新增 7 种分辨率（含 1920×1080 原图），共 7 档可选
  - 新增 images[].id 字段，便于业务侧做去重 / 收藏
  - 上游响应按 (cid, start_bucket=10) 桶化缓存 1h，节省 80% 上游请求
  - shuffle 始终在本地做，缓存命中也保证随机性
  - 错误细分：上游 HTTP 错 / errno!=0 / 列表为空 / 分类无该分辨率 → 不同 code

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/wallpaper`

Source: `https://apizero.cn/aidocs/wallpaper/raw.md`
Last updated: 2026-05-11T16:16:07+08:00