壁纸 API v2.0 — 免费高清壁纸接口文档

免费开放 · 稳定可靠 · 持续更新

高清壁纸
API 接口

双数据源自动切换，支持关键词搜索、分类筛选、多种分辨率。
302 直链或 JSON 数据，一行代码接入你的项目。

快速开始 → 在线演示

—

累计调用

分辨率可选

壁纸分类

数据源

↓ 查看文档

壁纸 API v2.0

免费开放 · 双数据源自动切换 · 支持关键词、分类、多分辨率

双数据源自动切换关键词 / 分类筛选 6 种分辨率 JSON + 302 双模式 60次/分钟限流调用统计

主数据源 birdpaper 失败时自动切换至必应每日壁纸兜底，保障服务 7×24 可用。文件缓存 5 分钟，减少上游请求压力。

快速开始

最简调用

URL

https://wp.upx8.com/api.php

img 标签直接使用

HTML

<img src="https://wp.upx8.com/api.php?category=nature&resolution=1920x1080"
     alt="随机风景壁纸" />

CSS 背景图

CSS

body {
  background: url('https://wp.upx8.com/api.php') center/cover;
}

获取 JSON 数据

JavaScript

const res  = await fetch('https://wp.upx8.com/api.php?format=json&content=风景&count=3');
const data = await res.json();
console.log(data.data); // 壁纸数组

接口参考

GET /api.php 获取壁纸（支持所有参数） ▶

参数	类型		说明	默认
format	string	可选	返回格式：`json` 或留空（302跳转）	302
content	string	可选	关键词搜索，最长 100 字符	—
category	string	可选	分类 key，见分类列表；与 content 同时传时 content 优先	—
resolution	string	可选	图片分辨率，见分辨率列表	1920x1080
count	integer	可选	返回数量，仅 JSON 模式有效，范围 1–10	1
stats	any	可选	传入任意值返回调用统计数据	—

302 模式响应

HTTP

HTTP/1.1 302 Found
Location: https://img.birdpaper.com.cn/xxx/1920x1080.jpg

JSON 模式响应

JSON

{
  "code":    200,
  "message": "success",
  "count":   1,
  "data": {
    "url":        "https://img.birdpaper.com.cn/xxx.jpg",
    "width":      1920,
    "height":     1080,
    "title":      "山间云海",
    "resolution": "1920x1080",
    "source":     "birdpaper"
  }
}

GET /api.php?stats=1 调用统计 ▶

JSON

{
  "code": 200,
  "data": {
    "total_calls":  12480,
    "today_calls":  342,
    "top_keywords": { "random": 5200, "风景": 1840 },
    "daily":         { "2025-04-30": 342 },
    "api_version":  "2.0"
  }
}

错误码

状态码	含义
200	成功（JSON 模式）
302	成功，已跳转至图片（默认模式）
429	请求过于频繁，触发限流
503	上游数据源暂时不可用（两路均失败）

分类列表

通过 category 参数传入英文 key 进行分类筛选，点击卡片可复制对应调用地址。

nature🏔 风景

anime🎌 动漫

game🎮 游戏

animal🐾 动物

city🏙 城市

abstract🎨 抽象

space🌌 宇宙

car🚗 汽车

girl👩 美女

sport⚽ 运动

支持的分辨率

1280x720 1366x768 1600x900 1920x1080（默认） 2560x1440 3840x2160

⚠️ birdpaper 数据源返回图片原始尺寸，resolution 参数对其仅作记录，不做强制缩放。必应数据源支持指定分辨率，但部分图片不含 4K 版本。

在线演示

选择参数后点击「获取」

调用统计

累计调用

—

今日调用

—

热门关键词

—

频率限制

每个 IP 每分钟最多请求 60 次，超出后返回 HTTP 429。基于文件实现，无需 Redis。

JSON

{
  "code":    429,
  "message": "请求过于频繁，请稍后再试",
  "limit":   "60次/60秒"
}

💡 如需调整限额，修改 config.php 中的 RATE_LIMIT_MAX 即可，无需改动其他文件。