Skip to main content

​
GET /api/random-wallpapers

Retrieve multiple random wallpapers from WallWidgy’s Cloudinary-hosted collection. This endpoint provides more detailed metadata and supports resolution-based filtering.
This endpoint uses Cloudinary as the image source and returns different metadata compared to /api/random-wallpaper. It’s designed for applications that need high-quality wallpapers with detailed information.

​
Query parameters

​
count
number
default:"1"
Number of random wallpapers to return. The endpoint fetches up to 500 results and randomly selects the requested count. Defaults to 1.
​
tag
string
Filter by tag. Use desktop for landscape-oriented wallpapers or mobile for portrait-oriented wallpapers. Tags are matched against Cloudinary resource tags.
​
resolution
string
Filter by minimum resolution. Accepted values:
  • 1080p - Minimum 1920x1080
  • 1440p - Minimum 2560x1440
  • 4k - Minimum 3840x2160
  • 8k - Minimum 7680x4320

​
Response

Returns an array of wallpaper objects with detailed metadata.
​
[].public_id
string
Cloudinary public identifier for the wallpaper
​
[].name
string
Filename of the wallpaper (extracted from public_id)
​
[].width
number
Width of the wallpaper in pixels
​
[].height
number
Height of the wallpaper in pixels
​
[].format
string
Image format (e.g., jpg, png, webp)
​
[].created_at
string
ISO 8601 timestamp of when the wallpaper was uploaded to Cloudinary
​
[].tags
array
Array of tags associated with the wallpaper
​
[].colors
array
Array of dominant colors detected in the wallpaper
​
[].preview_url
string
Optimized preview URL (600x400, cropped and auto-formatted)
​
[].download_url
string
Full-resolution download URL

​
Error responses

​
error
string
Error message describing what went wrong
500 Internal Server Error - Returned when there’s a server error or Cloudinary API fails

​
Examples

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

# Get 5 random desktop wallpapers
curl "https://wallwidgy.com/api/random-wallpapers?count=5&tag=desktop"

# Get 3 random 4K wallpapers
curl "https://wallwidgy.com/api/random-wallpapers?count=3&resolution=4k"

# Get 10 random mobile wallpapers in 1440p or higher
curl "https://wallwidgy.com/api/random-wallpapers?count=10&tag=mobile&resolution=1440p"

​
Example response

[
  {
    "public_id": "wallpapers/mountain_sunset_4k",
    "name": "mountain_sunset_4k",
    "width": 3840,
    "height": 2160,
    "format": "jpg",
    "created_at": "2024-03-15T10:30:00Z",
    "tags": ["desktop", "nature", "landscape"],
    "colors": ["#FF6B35", "#4A90E2", "#2C3E50"],
    "preview_url": "https://res.cloudinary.com/.../f_auto,q_auto,w_600,h_400,c_fill/wallpapers/mountain_sunset_4k",
    "download_url": "https://res.cloudinary.com/.../wallpapers/mountain_sunset_4k"
  }
]

​
Example response with multiple wallpapers

[
  {
    "public_id": "wallpapers/ocean_waves_mobile",
    "name": "ocean_waves_mobile",
    "width": 1080,
    "height": 2400,
    "format": "webp",
    "created_at": "2024-03-10T14:20:00Z",
    "tags": ["mobile", "nature", "water"],
    "colors": ["#1E88E5", "#00ACC1", "#0277BD"],
    "preview_url": "https://res.cloudinary.com/.../f_auto,q_auto,w_600,h_400,c_fill/wallpapers/ocean_waves_mobile",
    "download_url": "https://res.cloudinary.com/.../wallpapers/ocean_waves_mobile"
  },
  {
    "public_id": "wallpapers/forest_path_mobile",
    "name": "forest_path_mobile",
    "width": 1080,
    "height": 2340,
    "format": "jpg",
    "created_at": "2024-03-08T09:15:00Z",
    "tags": ["mobile", "nature", "forest"],
    "colors": ["#2E7D32", "#558B2F", "#33691E"],
    "preview_url": "https://res.cloudinary.com/.../f_auto,q_auto,w_600,h_400,c_fill/wallpapers/forest_path_mobile",
    "download_url": "https://res.cloudinary.com/.../wallpapers/forest_path_mobile"
  }
]

​
Example error response

{
  "error": "Failed to fetch wallpapers from Cloudinary"
}

​
Filtering behavior

​
Tag filtering

When you use the tag parameter with desktop or mobile, the endpoint:
  1. Fetches wallpapers with the matching tag from Cloudinary
  2. Additionally filters by orientation: desktop (width > height) or mobile (height > width)
  3. Randomly shuffles the results
  4. Returns the requested count

​
Resolution filtering

Resolution filtering is applied after tag filtering and ensures wallpapers meet minimum dimension requirements:
  • 1080p: At least 1920 pixels wide AND 1080 pixels tall
  • 1440p: At least 2560 pixels wide AND 1440 pixels tall
  • 4k: At least 3840 pixels wide AND 2160 pixels tall
  • 8k: At least 7680 pixels wide AND 4320 pixels tall

Build docs developers (and LLMs) love

Get started for freeTalk to us