Wallhaven API

⭐ Beginner's Pick Photography / API Key Intermediate HTTPS

Varies by plan (check documentation)

77 Score

Grade B

Visit Official Site Compare Alternatives

Overview

Wallhaven is a curated wallpaper community, and its API lets you search and browse its large collection of high-resolution wallpapers by keyword, category, and resolution. Public wallpapers can be accessed without an API key, while an API key unlocks NSFW and personal favorites. It is a great API for building custom wallpaper apps or desktop clients.

💡

Beginner Tip

Start with the /search endpoint without an API key to browse SFW wallpapers immediately — authentication is only needed to access adult-rated content or your personal account data.

Available Data

image URLs in multiple sizes

photographer credit

image dimensions

download link

color data

Use case: Integrate wallpapers data into web and mobile applications

Example Response

JSON Response

{
  "id": "Dwu85P9SOIk",
  "urls": {
    "full": "https://images.unsplash.com/photo-...",
    "regular": "https://images.unsplash.com/photo-...?w=1080",
    "thumb": "https://images.unsplash.com/photo-...?w=200"
  },
  "width": 4000,
  "height": 3000,
  "user": {
    "name": "John Doe",
    "username": "johndoe"
  }
}

Field Reference

data[].id Unique identifier for the wallpaper on Wallhaven.

data[].url URL to the wallpaper detail page on the Wallhaven website.

data[].path Direct URL to download the full-resolution wallpaper image file.

data[].resolution Image resolution in WxH format, such as 1920x1080 or 3840x2160.

data[].colors List of dominant hex color codes extracted from the wallpaper image.

Implementation Example

// ⚠️ Note: This URL may be a documentation page. Check official docs for actual API endpoint.
const url = "https://wallhaven.cc/help/api";
// Replace headers or query params with the values required by this API.
const response = await fetch(url, {
  headers: {
  "X-API-Key": "YOUR_API_KEY"
  }
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();
console.log(data);