Random Wallpaper API
Build custom tools, extensions, and integrations with our public API. Get random wallpapers programmatically and let chance decide.
Quick Start
curl -L https://www.readme.club/api/random-wallpaper Response:
{
"success": true,
"wallpaper": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Minimalist Mountains",
"author": "u/username",
"category": "minimalist",
"width": 480,
"height": 800,
"download_count": 42,
"urls": {
"thumbnail": "https://www.readme.club/...",
"download": "https://www.readme.club/..."
}
}
} What is it?
The Random Wallpaper API is a simple REST endpoint that returns a random wallpaper from our collection in JSON format. Each request gives you a different wallpaper, perfect for building tools that let chance decide what users see.
No authentication required, rate limiting enabled (100 requests/minute), and CORS enabled for browser-based applications.
Endpoint
/api/random-wallpaper Returns a random wallpaper with all metadata and URLs.
Response Fields
id UUID of the wallpaper title Wallpaper title author Author name (u/username, @username, or plain name) category minimalist, dark, light, pop_culture, custom, or other urls.thumbnail URL of the thumbnail image for preview urls.download REQUIRED: Proxy URL to download original file (BMP, PNG, etc.) with automatic tracking. urls.download_webp Proxy URL to download optimized WebP version with automatic tracking. urls.download_original Same as download, explicit alias for clarity. Code Examples
async function getRandomWallpaper() {
const response = await fetch('https://www.readme.club/api/random-wallpaper');
const data = await response.json();
if (data.success) {
const wallpaper = data.wallpaper;
console.log('Title:', wallpaper.title);
console.log('Author:', wallpaper.author);
console.log('Download original:', wallpaper.urls.download);
console.log('Download WebP:', wallpaper.urls.download_webp);
// Download the original file
window.location.href = wallpaper.urls.download;
// Or download the WebP version
// window.location.href = wallpaper.urls.download_webp;
return wallpaper;
}
return null;
} function getRandomWallpaper() {
$response = file_get_contents('https://www.readme.club/api/random-wallpaper');
$data = json_decode($response, true);
if ($data['success']) {
$wallpaper = $data['wallpaper'];
echo "Title: " . $wallpaper['title'] . "
";
echo "Author: " . $wallpaper['author'] . "
";
echo "Download: " . $wallpaper['urls']['download'] . "
";
// Download the wallpaper
header('Location: ' . $wallpaper['urls']['download']);
exit;
}
return null;
}
// Use it
$wallpaper = getRandomWallpaper(); import requests
def get_random_wallpaper():
response = requests.get('https://www.readme.club/api/random-wallpaper')
data = response.json()
if data.get('success'):
wallpaper = data['wallpaper']
print(f"Title: {wallpaper['title']}")
print(f"Author: {wallpaper['author']}")
print(f"Download: {wallpaper['urls']['download']}")
return wallpaper
return None
# Use it
wallpaper = get_random_wallpaper() Download Tracking
🔒 Security & Tracking: Proxy download is REQUIRED
The API provides proxy URLs for downloading wallpapers. These endpoints force download tracking by serving files directly from local storage. Direct file URLs are not exposed for security and statistics integrity.
Examples
// ✅ Download original file (BMP, PNG, etc.)
window.location.href = wallpaper.urls.download;
// ✅ Download optimized WebP version
window.location.href = wallpaper.urls.download_webp;
// The proxy ensures every download is automatically tracked How it works:
- Files are served directly from our servers
- The API reads from static files for optimal performance
- Every download is automatically tracked for statistics
- The proxy endpoint ensures data integrity and prevents untracked downloads
Use Cases
Chrome Extensions
Show a random wallpaper on new tabs. Perfect for users who love discovery.
Desktop Widgets
Create widgets that automatically change wallpapers on a schedule.
Custom Tools
Build batch downloaders, organizers, or integration tools for your workflow.
Automation
Scripts that automatically rotate wallpapers on your Xteink device.
CORS & Limits
CORS Enabled
The API is configured with Access-Control-Allow-Origin: *, making it perfect for browser extensions and client-side JavaScript applications.
No Authentication Required
The API is public and doesn't require any API keys or authentication. Just make a request and get a wallpaper.
Rate Limiting
The API has a rate limit of 100 requests per minute per IP address. This ensures fair usage and prevents abuse.
When the limit is exceeded, you'll receive a 429 Too Many Requests response with Retry-After header indicating when you can try again. Rate limit information is also included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
Stay Updated
Get notified about API updates, new features, and developer resources. Join our newsletter for the latest news.
Need Help? Want to Co-Build?
Stuck on something? Have a brilliant idea? Let's make it happen!
Whether you're building a Chrome extension, a desktop widget, or something completely new—I'm here to help. Reach out on Reddit and let's turn your ideas into reality. Your feedback and contributions shape the future of this API! 🚀
Share Your Creations
Built something cool with this API? Share your extensions, widgets, or tools with the community! Submit your creation to our resources page and help other developers discover your work.
Submit to Resources