Direct image responses
Endpoints under /api/wallpapers/random/image and /api/wallpapers/{id}/image
stream the actual image bytes, so one URL is enough for any automation tool.
Wallpaper Server Documentation
Wallpaper Server is a self-hosted Go application that turns your image folders into a filterable wallpaper API and a browser gallery. Its defining feature is that a single request can return the image itself — ready to save or set as a wallpaper — instead of metadata you then have to parse and download separately.
curl "http://localhost:8519/api/wallpapers/random/image" --output wallpaper.jpgChoose your path
Section titled “Choose your path” Install Wallpaper Server Build from source, run with Docker or install as a systemd service.
Configure image folders Point the server at one or more wallpaper folders with a small YAML file.
Retrieve a wallpaper Return a random or specific image directly over HTTP.
Filter by image properties Narrow results by brightness, dimensions, aspect ratio, colour and format.
Connect an automation tool Wire the direct-image endpoint into shell, Siri, Tasker or Home Assistant.
Browse the API Every endpoint, parameter, status code and response shape.
What it does
Section titled “What it does”Automatic classification
Every image is analysed for brightness, orientation, aspect ratio and dominant colour when it is scanned or uploaded.
Browser gallery
A built-in gallery at / lets you browse, filter, upload and delete
wallpapers, with infinite scrolling and lazy loading.
Self-hosted
A single Go binary with no external database. Configure it with YAML and run it on your own machine, a home server or in Docker.
Useful links
Section titled “Useful links”Wallpaper Server is distributed under the MIT License.