Developer Documentation

API Documentation

Integrate beautiful AI-generated wallpapers into your apps with our REST API.

Quick Start

curl -X GET "https://api.wallpaperapi.com/v1/wallpapers/random" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get your API key

Authentication

All API requests require authentication via Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Get your API key from your account dashboard.

Base URL

https://api.wallpaperapi.com/v1

All endpoints are relative to this base URL. The API uses JSON for both requests and responses.

Rate Limits

Plan	Requests/Day	Premium Access
Free	50	Preview only
Pro	5,000	Full access
API Pro	Unlimited	Full + Commercial

Rate limits reset daily at midnight UTC. Check response headers for current usage.

Endpoints

GET/api/v1/wallpapers

List all wallpapers with pagination and filtering

Parameters

category	string	Filter by category slug
style	string	Filter by style (abstract, photorealistic, etc.)
premium	boolean	Filter by premium status
limit	number	Results per page (default: 20, max: 100)
offset	number	Pagination offset

GET/api/v1/wallpapers/:id

Get a single wallpaper by ID

GET/api/v1/wallpapers/random

Get a random wallpaper

Parameters

resolution

string

Desired resolution (e.g., 1920x1080, 4k)

Example Response

{
  "data": {
    "id": 42,
    "title": "Neon City",
    "slug": "neon-city",
    "description": "Futuristic neon cityscape",
    "width": 3840,
    "height": 2160,
    "category": {
      "id": 4,
      "name": "Cyberpunk",
      "slug": "cyberpunk"
    },
    "urls": {
      "thumbnail": "https://cdn.../thumb/neon-city.jpg",
      "preview": "https://cdn.../preview/neon-city.jpg",
      "full": "https://cdn.../full/neon-city.jpg"
    },
    "is_premium": true,
    "downloads": 1542,
    "tags": ["cyberpunk", "city", "neon", "night"]
  }
}

Error Handling

Code	Meaning
401	Invalid or missing API key
403	Premium content, upgrade required
404	Resource not found
429	Rate limit exceeded
500	Server error