<!-- 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 |
| 每日免费额度 | 10000 次（已认证用户） |
| 匿名每日额度 | 2000 次（无 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. 请求示例

> AI 提示：以下 5 种语言示例都是可运行的，只需把 `YOUR_API_KEY` 替换为用户申请的实际 Key（https://apizero.cn/account/keys）。
> 优先选择用户问题中提到的语言；未指定时默认使用 Python。

### cURL

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

### Python

```python
import requests

resp = requests.get(
    "https://v1.apizero.cn/api/wallpaper",
    params={
    "category": "风景",
    "resolution": "1920x1080",
    "count": "5",
    "key": "YOUR_API_KEY",
},
    timeout=15,
)
resp.raise_for_status()
print(resp.json())
```

### JavaScript (Node.js)

```javascript
// Node.js 18+ / 浏览器原生 fetch
const params = new URLSearchParams({
  "category": "风景",
  "resolution": "1920x1080",
  "count": "5",
  "key": "YOUR_API_KEY",
});

const res = await fetch(`https://v1.apizero.cn/api/wallpaper?${params}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);
```

### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://v1.apizero.cn/api/wallpaper", nil)
	q := req.URL.Query()
	q.Set("category", "风景")
	q.Set("resolution", "1920x1080")
	q.Set("count", "5")
	q.Set("key", "YOUR_API_KEY")
	req.URL.RawQuery = q.Encode()

	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

### PHP

```php
<?php
$url = "https://v1.apizero.cn/api/wallpaper?" . http_build_query([
    "category" => "风景",
    "resolution" => "1920x1080",
    "count" => "5",
    "key" => "YOUR_API_KEY",
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
print_r($data);
```

## 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-08-09T19:30:08+08:00