Wallpaper Server

SELF-HOSTED WALLPAPER API · GO · PORT 8519

A wallpaper API for your image folders.

Turn your image folders into a self-hosted API and gallery. Filter by brightness, size, aspect ratio, orientation and colour — and get the image itself back. No JSON parsing required.

Get started View the API

Single Go binary · Docker · systemd · No database

GET http://localhost:8519/api/wallpapers/random/image ?brightness=dark &min_width=3840 &orientation=landscape

→ 200 OK · image/webp · raw image response

Dark night-sky wallpaper with layered mountain ridges under scattered stars
Dark wallpaper of jagged peaks beneath a faint teal aurora band
  • brightness: dark
  • orientation: landscape
  • luminance: 0.10

Fresh examples come from Unsplash. Wallpaper Server itself serves images from your own folders.

Raw image responses

The endpoint returns the file, not JSON.

Automatic classification

Luminance, colour and shape detected on scan.

One Go binary

A single process. Nothing else to run.

No external database

The index is built from your folders.

Docker + systemd

Container or boot service, your call.

01 — DIRECT API

One request. One image.

/api/wallpapers/random/image responds with the wallpaper itself — ready to save, set or pipe. Automation tools skip the metadata step entirely.

The usual way

  1. request JSON
  2. parse
  3. extract URL
  4. download image

Wallpaper Server

  1. request image
  2. done
terminal 
curl -o wallpaper.jpg \
  "http://localhost:8519/api/wallpapers/random/image?brightness=dark"

Also: /random/thumbnail for thumbnails, /{id}/image for a specific wallpaper.

02 — FILTERS

Filter results by image properties.

Every filter is computed automatically during scanning — combine them freely in one query string.

Brightness

?brightness=dark

Every image is graded light, medium or dark by luminance while it is scanned.

Dominant colour

?dominant_hue=cool

Images are sorted into red, green, blue, warm, cool or neutral by dominant colour.

Dimensions

?min_width=3840

Bound width and height to guarantee the resolution a screen actually needs.

Aspect ratio

?aspect_ratio=ultrawide

Filter by 16:9, 4:3, ultrawide, square or portrait shapes.

Orientation

?orientation=portrait

Landscape, portrait or square — pick what fits the device.

Format

?format=webp

Constrain results to a specific file type when it matters.

Cache & thumbnails

/random/thumbnail

Processed images and thumbnails are cached on disk, so repeat requests skip reprocessing.

Multiple folders

wallpaper_folders

List any number of directories in your config; every folder feeds one shared index and one API.

03 — AUTOMATIC ANALYSIS

Scan once. Filter automatically.

Point the server at your folders. Every image is measured and indexed before it's ever requested.

  1. 01

    Discover

    Configured folders are scanned; uploads land in the same pipeline.

  2. 02

    Analyse

    Luminance, dimensions, orientation, aspect-ratio category and dominant hue are computed per image.

  3. 03

    Index & serve

    The wallpaper becomes available to filtered API calls and the gallery.

Wallpaper of orange sunset light over layered desert dunes
metadata 
{
  "filename": "warm-dune.webp",
  "width": 2560, "height": 1440,
  "brightness": "medium",
  "aspect_ratio": "16:9",
  "orientation": "landscape",
  "dominant_hue": "warm",
  "luminance": 0.62
}

05 — AUTOMATION

Automation examples.

Anything that can fetch a URL can set a wallpaper. These are the exact recipes from the README.

crontab -e 
# crontab -e — light mornings, dark evenings
0 8  * * * curl -s -o ~/wallpaper.jpg "http://your-server:8519/api/wallpapers/random/image?brightness=light" && gsettings set org.gnome.desktop.background picture-uri "file://$(realpath ~/wallpaper.jpg)"
0 20 * * * curl -s -o ~/wallpaper.jpg "http://your-server:8519/api/wallpapers/random/image?brightness=dark"  && gsettings set org.gnome.desktop.background picture-uri "file://$(realpath ~/wallpaper.jpg)"
Full recipes in the README →

06 — DEPLOY

One binary. One config. No database.

Build it with Go, point it at a folder, and it's serving on port 8519.

terminal 
git clone https://github.com/Ajaymamtora/wallpaper-server.git
cd wallpaper-server
go build -o wallpaper-server
./wallpaper-server --config config.yaml --start
config.yaml 
server:
  host: "0.0.0.0"
  port: 8519
wallpaper_folders:
  - "~/Pictures/Wallpapers"
cache_dir: "~/.cache/wallpaper-server"
uploads_dir: "~/.local/share/wallpaper-server/uploads"
supported_extensions: [".jpg", ".jpeg", ".png", ".webp"]

Docker

docker build -t wallpaper-server .

Multi-stage image, runs as non-root, EXPOSE 8519.

systemd

sudo ./wallpaper-server --autostart --config /path/to/config.yaml

Installs and enables a boot service.

Defaults

  • port 8519
  • config ~/.config/wallpaper-server/config.yaml
  • cache ~/.cache/wallpaper-server (XDG)

07 — API SURFACE

Every endpoint, at a glance.

Same filter query string everywhere it makes sense.

Retrieve

  • GET /api/wallpapers/random/image Random image file
  • GET /api/wallpapers/random/thumbnail Random thumbnail
  • GET /api/wallpapers/{id}/image Specific image
  • GET /api/wallpapers/{id}/thumbnail Specific thumbnail

Query

  • GET /api/wallpapers List + filters
  • GET /api/wallpapers/random Random metadata
  • GET /api/wallpapers/{id} Metadata by id

Manage

  • POST /api/upload Multipart upload
  • POST /api/refresh Rescan folders
  • DELETE /api/wallpapers/{id} Delete
  • GET/PUT /api/settings Read / update config
  • GET /api/info API info + examples
Full reference →

08 — SELF-HOSTED

Runs entirely on your own hardware.

Images are scanned, analysed and served entirely on your own hardware. There is no hosted processing step and no account required — one server can serve every phone, desktop and dashboard on your network.

09 — FAQ

Frequently asked questions.

Does it require a database?

No. It's a single Go binary and a single process. The wallpaper index is built by scanning your folders, and processed images are cached on disk — ~/.cache/wallpaper-server by default.

Can it serve from multiple folders?

Yes. List any number of directories under wallpaper_folders in config.yaml; they're all scanned into one index and served through the same API.

How are wallpapers classified?

Automatically, during scanning and upload. The server measures luminance, dimensions, orientation, aspect-ratio category and dominant hue for every image — no manual tagging.

Can an endpoint return the image directly?

Yes — that's the point. /api/wallpapers/random/image and /api/wallpapers/{id}/image respond with the image file itself, so a single URL is enough for Shortcuts, Tasker or curl.

Which image formats are supported?

.jpg, .jpeg, .png and .webp by default — configurable via supported_extensions.

Can I upload from the browser?

Yes. The gallery supports drag-and-drop upload, and there's a POST /api/upload endpoint for multipart uploads. Uploads are analysed and indexed immediately.

Does it run in Docker or under systemd?

Both. A multi-stage Dockerfile is included, and sudo ./wallpaper-server --autostart installs a systemd service that starts on boot.

Does it work with Home Assistant, Tasker or Siri Shortcuts?

Yes — any tool that can fetch a URL. The README ships recipes for all three, plus cron and multi-monitor scripts.

Turn your wallpaper folder into an API.

Self-hosted. Single binary. Direct image responses.

Get started Read the docs