Skip to content
Wallpaper Server Wallpaper Server Docs

Filtering Wallpapers

Every retrieval endpoint that returns a random or listed wallpaper accepts the same filter query parameters. This guide shows how to combine them; the Filter Reference is the exhaustive table.

How filters combine

Section titled “How filters combine”

Filters are ANDed together: a wallpaper must satisfy all the filters you supply. An omitted parameter — or one set to any — imposes no constraint.

Terminal window
# Dark AND ultrawide AND cool-toned
curl "http://localhost:8519/api/wallpapers/random/image?brightness=dark&aspect_ratio=ultrawide&dominant_hue=cool" \
  --output wallpaper.jpg

What you can filter by

Section titled “What you can filter by”
  • Brightness — light, dark, medium.
  • Orientation — landscape, portrait, square.
  • Aspect ratio — 16:9, 4:3, ultrawide, square, portrait, custom.
  • Dominant colour — red, green, blue, warm, cool, neutral.
  • Format — jpg, jpeg, png, webp.
  • Dimensions — min_width, min_height, max_width, max_height in pixels (inclusive bounds).

These categories come from automatic image analysis, which runs when images are scanned or uploaded.

Recipes

Section titled “Recipes”
Terminal window
# A dark wallpaper for a phone
curl "http://localhost:8519/api/wallpapers/random/image?brightness=dark&orientation=portrait" -o phone.jpg


# A bright desktop background
curl "http://localhost:8519/api/wallpapers/random/image?brightness=light&orientation=landscape" -o desktop.jpg


# Only true 4K (or larger) landscapes
curl "http://localhost:8519/api/wallpapers/random/image?min_width=3840&min_height=2160" -o uhd.jpg


# A warm-toned square PNG
curl "http://localhost:8519/api/wallpapers/random/image?dominant_hue=warm&aspect_ratio=square&format=png" -o warm.jpg

When nothing matches

Section titled “When nothing matches”

If your filters exclude every wallpaper:

  • The list endpoint (/api/wallpapers) returns an empty wallpapers array.
  • The random endpoints return 404 Not Found.

Loosen a filter or set it to any to widen the results.

Section titled “Related”