搜索接口的参数全对照
搜索接口是整套 API 的核心：wallhaven.cc/api/v1/search，全部参数通过 URL 查询串传递。下面是官方文档的参数全表。
搜索词 q
支持网页搜索框同款操作符：q=nature 模糊匹配、q=-city 排除、q=+space +minimal 组合、q=@用户名 按上传者、q=id:123 精确标签、q=type:png 文件类型、q=like:壁纸ID 找相似。
过滤参数
| 参数 | 取值 | 说明 |
|---|---|---|
| categories | 100 / 010 / 001（可组合） | 依次对应 General/Anime/People，1 开 0 关，默认 111 |
| purity | 100 / 110 / 111 | 依次对应 SFW/Sketchy/NSFW；NSFW 必须带密钥 |
| atleast | 如 1920x1080 | 最低分辨率下限 |
| resolutions | 逗号分隔多档 | 精确分辨率 |
| ratios | 如 16x9,16x10 | 宽高比 |
| colors | 六位色值（如 0066cc） | 主色，29 色板之一 |
排序与翻页
| 参数 | 取值 |
|---|---|
| sorting | date_added（默认）/ relevance / random / views / favorites / toplist |
| order | desc（默认）/ asc |
| topRange | 1d / 3d / 1w / 1M（默认）/ 3M / 6M / 1y，仅 toplist 生效 |
| page | 页码 |
| seed | 六位字母数字，random 翻页去重用 |
返回结构与分页
每页固定 24 张。每张图带 id、url、短链（whvn.cc）、uploader、views、favorites、purity、category、resolution、ratio、file_type、file_size、created_at、colors（五色数组）、path（原图地址）、thumbs（三种缩略图）。meta 里是 current_page、last_page、per_page、total——翻页逻辑照 meta 走即可。
两个高频坑
id:精确标签不能与别的操作符同用，混用无效。- 不带密钥的搜索按游客口径执行（纯 SFW）；带密钥则套用账号的默认筛选——同一 URL 两种结果，调脚本时注意。
接下来去哪
- 读单图与标签的端点：看 单图、标签与收藏夹三类读取接口。
- 限流与报错处理：看 每分钟 45 次的限流与两类报错。