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-Typeset to the image’s own type (for exampleimage/jpeg,image/png,image/webp).Content-Disposition: inlinewith 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”curl "http://localhost:8519/api/wallpapers/random/image" --output wallpaper.jpgcurl "http://localhost:8519/api/wallpapers/random/image?brightness=dark&aspect_ratio=ultrawide" \ --output wallpaper.jpgcurl "http://localhost:8519/api/wallpapers/<id>/image" --output wallpaper.jpgcurl "http://localhost:8519/api/wallpapers/random/thumbnail" --output thumb.jpgYou 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.
Related
Section titled “Related”- Querying metadata — get JSON, including a
wallpaper’s
id, before requesting a specific image. - Filtering wallpapers — practical filter recipes.