Wallwidgy API

Access thousands of high-quality wallpapers programmatically with our simple REST API

Quick Start

Get started with a simple GET request to retrieve random wallpapers:

bash

curl https://wallwidgy.vercel.app/api/wallpapers

Live API: The API is now live and ready to use! No authentication required.

Features

Random Selection

Get randomized wallpapers on each request for variety and discovery.

Category Filtering

Filter by categories like nature, minimal, abstract, and more.

Device Optimization

Get desktop or mobile optimized wallpapers based on your needs.

CORS Enabled

Use from any domain - perfect for web apps and browser extensions.

Endpoints

GET/api/wallpapers

Retrieve random wallpapers with optional filtering parameters.

Query Parameters

type

Optional

desktop | mobile

Filter by device type

category

Optional

string

Filter by category folder

color

Optional

string

Filter by primary/secondary colors

count

Optional

1-10

Number of wallpapers (default: 1)

Examples

Get a Random Wallpaper

bash

curl https://wallwidgy.vercel.app/api/wallpapers

Response:

json

{
  "wallpapers": [
    "https://wallwidgy.vercel.app/wallpapers/nature/mountain-sunset.jpg"
  ],
  "count": 1,
  "category": "all",
  "type": "all",
  "color": "all"
}

Get Desktop Wallpapers

bash

curl https://wallwidgy.vercel.app/api/wallpapers?type=desktop&count=3

Get Wallpapers by Category

bash

curl https://wallwidgy.vercel.app/api/wallpapers?category=minimal&count=2

Get Wallpapers by Color

bash

curl https://wallwidgy.vercel.app/api/wallpapers?color=blue&count=3

Filter wallpapers by primary or secondary colors. Common colors include:blueredgreenpurplepinkblackwhiteand more.

Combine Multiple Filters

bash

curl https://wallwidgy.vercel.app/api/wallpapers?category=art&type=desktop&color=purple&count=4

You can combine category, type, color, and count parameters for precise filtering.

JavaScript/Fetch Example

javascript

fetch('https://wallwidgy.vercel.app/api/wallpapers?type=mobile&count=5')
  .then(response => response.json())
  .then(data => {
    console.log('Wallpapers:', data.wallpapers);
    // Use the wallpaper URLs
    data.wallpapers.forEach(url => {
      console.log('Wallpaper URL:', url);
    });
  })
  .catch(error => console.error('Error:', error));

Available Categories

Current categories available in our wallpaper collection:

abstract

anime

architecture

art

cars

minimal

nature

tech

Note: Categories are based on folder structure in /public/wallpapers/

Available Colors

Filter wallpapers by their primary or secondary colors. Here are the most common colors available:

blue

red

green

purple

pink

orange

yellow

cyan

black

white

gray

brown

gold

silver

crimson

navy

teal

violet

magenta

azure

lime

tan

coral

lavender

Tip: Colors are matched against both primary and secondary color data from our wallpaper index. Try specific color names for best results!

Usage Guidelines

Fair Usage

• No authentication required
• Please be respectful with request frequency
• Maximum 10 wallpapers per request
• All wallpapers are for personal use

Attribution

• Attribution is appreciated but not required
• Link back to wallwidgy.vercel.app
• Respect copyright of original creators
• Report any issues via GitHub

Ready to integrate?

Start using the Wallwidgy API in your projects today. No registration required.

View Wallpapers GitHub