Developer API

Random Wallpaper API

Build custom tools, extensions, and integrations with our public API. Get random wallpapers programmatically and let chance decide.

Public API
CORS Enabled
No Authentication

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

GET /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

JavaScript
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;
}
PHP
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();
Python
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.

Let's Build Together

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