Skip to content
Wallpaper Server Wallpaper Server Docs

Retrieving Images

These endpoints return the image itself. The response body is binary image data — save it to a file or hand it straight to a wallpaper-setting tool. Do not parse it as JSON.

Endpoints

Section titled “Endpoints”
Method Path Returns
GET /api/wallpapers/random/image A random matching wallpaper
GET /api/wallpapers/random/thumbnail A JPEG thumbnail of a random match
GET /api/wallpapers/{id}/image A specific wallpaper by ID
GET /api/wallpapers/{id}/thumbnail A JPEG thumbnail of a specific wallpaper

All four accept filter parameters where a random selection is involved.

Response headers

Section titled “Response headers”

Full images are served with:

  • Content-Type set to the image’s own type (for example image/jpeg, image/png, image/webp).
  • Content-Disposition: inline with the original filename.
  • Cache-Control: public, max-age=3600.

Thumbnails are always served as image/jpeg at up to 300×200 pixels.

Because the endpoints stream the file directly (no redirect), curl does not need the -L flag.

Examples

Section titled “Examples”
Terminal window
curl "http://localhost:8519/api/wallpapers/random/image" --output wallpaper.jpg

You can also open any of these URLs directly in a browser.

No matching wallpaper

Section titled “No matching wallpaper”

If filters exclude every wallpaper, the random image endpoints respond with 404 Not Found and a plain-text body. Requesting an unknown {id} also returns 404. See Errors.

Section titled “Related”