A
APIs Score

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);

What Can You Build?

Note: These code examples are AI-generated and unverified. Always refer to the official API documentation for accurate usage.

Common Errors & Troubleshooting

HTTP 401 Unauthorized on account endpoints The endpoint requires authentication and either no API key was provided or it is invalid.
✓ Log into wallhaven.cc, go to Account Settings > API Key, generate a key, and include it as the X-API-Key header.
Empty results on search The purity or category filter combination excludes all results for the given query.
✓ Broaden your search by setting categories=111 and purity=100 to include all SFW categories.
HTTP 429 Too Many Requests Wallhaven enforces rate limits on API access.
✓ Add a delay between requests (at least 1 second) and cache responses to avoid hitting limits.

API Score Breakdown

🌐 Reachability 30/30
⚡ Speed 10/20
🔒 Security 15/15
🛠 Developer XP 12/20
✓ Reliability 10/15

Partially tested on Apr 5, 2026

How is this scored? →

Technical Specifications

Auth API Key
HTTPS REQUIRED
CORS UNKNOWN
Category Photography
Difficulty Intermediate
Verified: 2026-04-04

Similar APIs

View All →

APITemplate.io

77

APITemplate.io lets you generate images and PDFs on the fly by filling data into pre-designed templates.

API Key Intermediate HTTPS

Bruzu

⚠ Unavailable
0

Bruzu provides programmatic access to image generation with query string via REST API.

API Key Intermediate HTTPS

CheetahO

72

CheetahO is an image optimization API that compresses and resizes photos without visible quality loss.

API Key Intermediate HTTPS

Dagpi

⭐ Beginner's Pick
72

Dagpi is a free image manipulation API that applies filters, effects, and fun transformations to images with a single HTTP request.

API Key Intermediate HTTPS

Duply

⚠ Unavailable
0

Duply provides programmatic access to generate, edit, scale and manage images and videos smarter & faster via REST API.

API Key Intermediate HTTPS