Wallhaven Downloader

Use the bundled script to download wallpapers from Wallhaven API with custom parameters.

Command

python3 {baseDir}/scripts/wallhaven_download.py \
  --apikey "<API_KEY>" \
  --count 20 \
  --out "/home/node/.openclaw/workspace/downloads/n1" \
  --categories 111 \
  --purity 001 \
  --sorting toplist \
  --order desc \
  --topRange 1M

# or parse directly from wallhaven search URL
python3 {baseDir}/scripts/wallhaven_download.py \
  --apikey "<API_KEY>" \
  --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"

Inputs

• --apikey (optional): Wallhaven API key. Required for NSFW (purity includes last bit = 1) and private/user-filtered results.
• --search-url (optional): Paste a Wallhaven search URL; script auto-parses supported query parameters.
• --count: Total number of images to download.
• --out: Output directory.
• --base-url: 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

# 1) Toplist (last month), NSFW only, download 20
python3 {baseDir}/scripts/wallhaven_download.py \
  --apikey "<API_KEY>" \
  --count 20 \
  --out "./downloads/n1" \
  --categories 111 \
  --purity 001 \
  --sorting toplist \
  --order desc \
  --topRange 1M

# 2) Keyword search (SFW), minimum resolution 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) Random with seed (reproducible pagination)
python3 {baseDir}/scripts/wallhaven_download.py \
  --count 48 \
  --out "./downloads/random-set" \
  --sorting random \
  --seed abc123

Parameter Guide (Wallhaven API)