Wallhaven Downloader
Use the bundled script to download wallpapers from Wallhaven API with custom parameters.
Command
CODEBLOCK0
Inputs
- -
--apikey (optional): Wallhaven API key. Required for NSFW (purity includes last bit = 1) and private/user-filtered results. - INLINECODE3 (optional): Paste a Wallhaven search URL; script auto-parses supported query parameters.
- INLINECODE4 : Total number of images to download.
- INLINECODE5 : Output directory.
- INLINECODE6 : API endpoint (default:
https://wallhaven.cc/api/v1/search). Restricted to Wallhaven API hosts for safety. - Any API search parameter as
--<name> <value> (e.g. --q, --categories, --purity, --sorting, --order, --topRange, --atleast, --resolutions, --ratios, --colors, --seed, --page). - When both
--search-url and explicit --<name> <value> are provided, explicit args override URL values.
Behavior
- - Auto-paginates until requested count is reached or no more results.
- Reads
meta.last_page and stops safely. - Downloads from each result
path URL after strict safety validation. - Names files with index + wallpaper id:
01-wallhaven-<id>.<ext>. - Writes
manifest.json with source query and downloaded items.
Common Examples
CODEBLOCK1
Parameter Guide (Wallhaven API)
- -
q: fuzzy query / advanced query operators (+tag, -tag, @user, type:png, like:<id>) - INLINECODE33 : 3-bit switch (general/anime/people), e.g.
111, 100, INLINECODE36 - INLINECODE37 : 3-bit switch (sfw/sketchy/nsfw), e.g.
100, 110, 001 (NSFW needs valid API key) - INLINECODE41 :
date_added, relevance, random, views, favorites, INLINECODE47 - INLINECODE48 :
desc or INLINECODE50 - INLINECODE51 :
1d, 3d, 1w, 1M, 3M, 6M, 1y (works with sorting=toplist) - INLINECODE60 : minimum resolution (e.g.
1920x1080) - INLINECODE62 : exact resolutions, comma-separated
- INLINECODE63 : aspect ratios, comma-separated (e.g.
16x9,21x9) - INLINECODE65 : hex color (no
#, e.g. ff6600) - INLINECODE68 : seed for random listing pagination
- INLINECODE69 : manual start page (script will keep paginating)
Output
- - Downloaded files:
01-wallhaven-<id>.<ext>, INLINECODE71 - Manifest: INLINECODE72
- includes requested count, actual downloaded count, resolved params, and per-item metadata
Notes
- - API limit is 45 requests/min. Script inserts a small delay between page requests.
- Do not hardcode API keys in the skill/script. Pass via
--apikey or WALLHAVEN_API_KEY only. - Security guardrails: only
https://wallhaven.cc API endpoints and https://w.wallhaven.cc image URLs are accepted; local/private/non-HTTPS hosts are rejected. - If API returns errors, script exits with clear message.
- If fewer results exist than requested, script downloads available items and reports actual count.
Wallhaven 下载器
使用捆绑脚本通过自定义参数从 Wallhaven API 下载壁纸。
命令
bash
python3 {baseDir}/scripts/wallhaven_download.py \
--apikey \
--count 20 \
--out /home/node/.openclaw/workspace/downloads/n1 \
--categories 111 \
--purity 001 \
--sorting toplist \
--order desc \
--topRange 1M
或直接从 Wallhaven 搜索 URL 解析
python3 {baseDir}/scripts/wallhaven_download.py \
--apikey
\
--count 20 \
--out /home/node/.openclaw/workspace/downloads/n1 \
--search-url https://wallhaven.cc/search?categories=111&purity=001&sorting=toplist&order=desc&topRange=1M
输入参数
- - --apikey（可选）：Wallhaven API 密钥。获取 NSFW（purity 包含最后一位 1）和私人/用户筛选结果时需要。
- --search-url（可选）：粘贴 Wallhaven 搜索 URL；脚本自动解析支持的查询参数。
- --count：要下载的图片总数。
- --out：输出目录。
- --base-url：API 端点（默认：https://wallhaven.cc/api/v1/search）。出于安全考虑，仅限 Wallhaven API 主机。
- 任何 API 搜索参数均可作为 --<名称> <值> 使用（例如 --q、--categories、--purity、--sorting、--order、--topRange、--atleast、--resolutions、--ratios、--colors、--seed、--page）。
- 当同时提供 --search-url 和显式 --<名称> <值> 时，显式参数会覆盖 URL 中的值。
行为
- - 自动翻页，直到达到请求数量或没有更多结果。
- 读取 meta.last_page 并安全停止。
- 经过严格安全验证后，从每个结果的 path URL 下载。
- 使用索引 + 壁纸 ID 命名文件：01-wallhaven-.<扩展名>。
- 写入 manifest.json，包含源查询和下载项。
常见示例
bash
1) 排行榜（上个月），仅 NSFW，下载 20 张
python3 {baseDir}/scripts/wallhaven_download.py \
--apikey \
--count 20 \
--out ./downloads/n1 \
--categories 111 \
--purity 001 \
--sorting toplist \
--order desc \
--topRange 1M
2) 关键词搜索（SFW），最低分辨率 2560x1440
python3 {baseDir}/scripts/wallhaven_download.py \
--count 30 \
--out ./downloads/city-night \
--q city night \
--categories 100 \
--purity 100 \
--sorting relevance \
--atleast 2560x1440
3) 带种子的随机（可重复分页）
python3 {baseDir}/scripts/wallhaven_download.py \
--count 48 \
--out ./downloads/random-set \
--sorting random \
--seed abc123
参数指南（Wallhaven API）
- - q：模糊查询/高级查询运算符（+tag、-tag、@user、type:png、like:）
- categories：3 位开关（通用/动漫/人物），例如 111、100、010
- purity：3 位开关（安全/草图/成人），例如 100、110、001（NSFW 需要有效 API 密钥）
- sorting：date_added、relevance、random、views、favorites、toplist
- order：desc 或 asc
- topRange：1d、3d、1w、1M、3M、6M、1y（与 sorting=toplist 配合使用）
- atleast：最低分辨率（例如 1920x1080）
- resolutions：精确分辨率，逗号分隔
- ratios：宽高比，逗号分隔（例如 16x9,21x9）
- colors：十六进制颜色（不带 #，例如 ff6600）
- seed：随机列表分页的种子
- page：手动起始页（脚本将继续翻页）
输出
- - 下载的文件：01-wallhaven-.<扩展名>、02-...
- 清单：/manifest.json
- 包含请求数量、实际下载数量、解析参数和每个项目的元数据
注意事项
- - API 限制为每分钟 45 次请求。脚本在页面请求之间插入小延迟。
- 不要在技能/脚本中硬编码 API 密钥。仅通过 --apikey 或 WALLHAVENAPIKEY 传递。
- 安全防护：仅接受 https://wallhaven.cc API 端点和 https://w.wallhaven.cc 图片 URL；拒绝本地/私有/非 HTTPS 主机。
- 如果 API 返回错误，脚本将退出并显示清晰的消息。
- 如果存在的结果少于请求数量，脚本将下载可用项目并报告实际数量。
