Skip to main content

​
GET /api/random-wallpaper

Retrieve a single random wallpaper from WallWidgy’s collection. You can filter by device type (desktop/mobile), category, or color to get wallpapers that match your specific needs.

​
Query parameters

​
type
string
Filter by device type. Accepts desktop or mobile. Desktop wallpapers have landscape orientation, while mobile wallpapers have portrait orientation.
​
category
string
Filter by category name. Categories are extracted from wallpaper filenames (e.g., nature, abstract, space).
​
color
string
Filter by primary or secondary color. Use lowercase color names (e.g., blue, red, green).
​
count
number
default:"1"
Number of random wallpapers to return. Must be between 1 and 10. Defaults to 1.

​
Response

​
wallpapers
array
Array of wallpaper URLs
​
[url]
string
Full URL to the wallpaper image
​
count
number
Number of wallpapers returned in the response
​
category
string
The category filter applied, or all if no filter was used
​
type
string
The device type filter applied, or all if no filter was used
​
color
string
The color filter applied, or all if no filter was used

​
Error responses

​
error
string
Error message describing what went wrong
404 Not Found - Returned when no wallpapers match the specified filters 500 Internal Server Error - Returned when there’s a server error

​
Examples

# Get a single random wallpaper
curl https://wallwidgy.com/api/random-wallpaper

# Get a random desktop wallpaper
curl "https://wallwidgy.com/api/random-wallpaper?type=desktop"

# Get 3 random mobile wallpapers from the nature category
curl "https://wallwidgy.com/api/random-wallpaper?type=mobile&category=nature&count=3"

# Get a random wallpaper with blue color
curl "https://wallwidgy.com/api/random-wallpaper?color=blue"

​
Example response

{
  "wallpapers": [
    "https://wallwidgy.com/wallpapers/nature_forest_001.jpg"
  ],
  "count": 1,
  "category": "all",
  "type": "all",
  "color": "all"
}

​
Example response with filters

{
  "wallpapers": [
    "https://wallwidgy.com/wallpapers/space_nebula_desktop_01.jpg",
    "https://wallwidgy.com/wallpapers/space_galaxy_desktop_03.jpg"
  ],
  "count": 2,
  "category": "space",
  "type": "desktop",
  "color": "all"
}

​
Example error response

{
  "error": "Category 'invalid' not found"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us