xianyan/docs/api_reference.md

# 壁纸图库 API 接口文档

> Base URL: `http://bz.wktyl.com`  
> 更新: 2026-05-01  
> 可用接口: 12个 | 已下线: Reddit(被墙25s)、ArtPexels(10s+超时)、Wallhaven(5s+超时)

---

## 通用参数

| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| limit | int | 20 | 每页条数 (1-50) |
| page | int | 1 | 页码 |
| category | string | all | 分类筛选 |
| sort | string | hot | 排序: hot/new |
| search | string | - | 搜索关键词 |

## 通用响应结构

```json
{
  "success": true,
  "data": [{ "id": "...", "resource_info": {}, "classification": {}, "media": {}, "statistics": {}, "metadata": {}, "supplementary": {} }],
  "pagination": { "current_page": 1, "total_pages": 10, "total_items": 200, "items_per_page": 20, "has_next": true },
  "query_params": {},
  "timestamp": "2026-05-01T12:00:00+08:00"
}
```

## 数据项字段

| 字段 | 说明 |
|------|------|
| id | 唯一标识 |
| resource_info | 资源信息: title/subtitle/description/keywords/language/source_type |
| classification | 分类: primary_category/categories/tags/tag_count/content_rating/style |
| media | 媒体: image_url/thumbnail_url/preview_url/download_url/width/height/resolution/aspect_ratio/format/file_size |
| statistics | 统计: views/downloads/likes/popularity_score/trend |
| metadata | 元数据: source/source_url/created_at/license/quality |
| supplementary | 补充: usage_scenarios/devices_compatible |

---

## 接口列表

### ⚡ 极速梯队 (<200ms)

#### 📷 Unsplash — `/api_unsplash.php`

⚡ 138ms | 摄影作品 | fallback 200条

```
GET /api_unsplash.php?limit=20&page=1&category=nature&sort=hot&search=wallpaper
```

```python
import requests
r = requests.get('http://bz.wktyl.com/api_unsplash.php', params={'limit': 10, 'page': 1})
data = r.json()
for item in data['data']:
    print(item['resource_info']['title'], item['media']['image_url'])
```

```swift
let url = URL(string: "http://bz.wktyl.com/api_unsplash.php?limit=10&page=1")!
let (data, _) = try await URLSession.shared.data(from: url)
let json = try JSONSerialization.jsonObject(with: data)
```

---

#### 🏙 WallSt — `/api_wallstreet.php`

⚡ 140ms | AI壁纸 | live 120条

```
GET /api_wallstreet.php?limit=20&page=1
```

```python
r = requests.get('http://bz.wktyl.com/api_wallstreet.php', params={'limit': 10})
```

---

#### 🎞 Pexels — `/api_pexels.php`

⚡ 136ms | 高清图库 | fallback 200条

```
GET /api_pexels.php?limit=20&page=1&category=nature&sort=hot&search=sky
```

```python
r = requests.get('http://bz.wktyl.com/api_pexels.php', params={'limit': 10})
```

---

#### 🔍 Pixabay — `/api_pixabay.php`

⚡ 140ms | 综合图库 | fallback 200条

```
GET /api_pixabay.php?limit=20&page=1&category=animal&search=cat
```

```python
r = requests.get('http://bz.wktyl.com/api_pixabay.php', params={'limit': 10, 'search': 'cat'})
```

---

#### 🖼 360壁纸 — `/api_360_bing.php?source=360`

⚡ 264ms | 360精选 | live 180条

```
GET /api_360_bing.php?source=360&limit=20&page=1
```

```python
r = requests.get('http://bz.wktyl.com/api_360_bing.php', params={'source': '360', 'limit': 10})
```

---

#### 🌍 必应壁纸 — `/api_360_bing.php?source=bing`

⚡ 245ms | 每日精选 | live 300条

```
GET /api_360_bing.php?source=bing&limit=20&page=1
```

```python
r = requests.get('http://bz.wktyl.com/api_360_bing.php', params={'source': 'bing', 'limit': 10})
```

---

### ✅ 稳定梯队 (200ms~1s)

#### 🚀 NASA — `/api_nasa.php`

✅ 133ms | 天文壁纸 | live缓存

```
GET /api_nasa.php?limit=20&page=1
```

```python
r = requests.get('http://bz.wktyl.com/api_nasa.php', params={'limit': 10})
```

特有字段: `metadata.nasa_id` / `classification.center` / `supplementary.concepts`

---

#### 🏔 壁纸 — `/api_hao_wallpaper.php`

✅ 345ms | 精选壁纸 | live 60条

```
GET /api_hao_wallpaper.php?limit=20&page=1
```

```python
r = requests.get('http://bz.wktyl.com/api_hao_wallpaper.php', params={'limit': 10})
```

---

#### 🎲 多多 — `/api_bizhiduoduo.php`

✅ 2102ms | 多多壁纸 | live 125条

```
GET /api_bizhiduoduo.php?action=random&limit=20&page=1
```

```python
r = requests.get('http://bz.wktyl.com/api_bizhiduoduo.php', params={'action': 'random', 'limit': 10})
```

额外 action: `categories` 获取分类列表

---

### 🌀 一般梯队 (1~3s)

#### 🔮 Bing+ — `/api_bing_enhanced.php`

🌀 371ms | 增强必应 | live 120条

```
GET /api_bing_enhanced.php?limit=20&page=1
```

```python
r = requests.get('http://bz.wktyl.com/api_bing_enhanced.php', params={'limit': 10})
```

---

#### 🎨 动漫 — `/api_anime_pictures.php`

🌀 2432ms | 动漫插画 | live 120条

```
GET /api_anime_pictures.php?limit=20&page=1&category=anime&search=girl
```

```python
r = requests.get('http://bz.wktyl.com/api_anime_pictures.php', params={'limit': 10, 'search': 'girl'})
```

特有字段: `classification.genre` / `metadata.author` / `supplementary.characters`

---

### 🐢 较慢梯队 (>3s)

#### 🌸 二次元 — `/api_dmoe.php`

🐢 2807ms | 随机二次元 | live 100条

```
GET /api_dmoe.php?limit=10&page=1
```

```python
r = requests.get('http://bz.wktyl.com/api_dmoe.php', params={'limit': 10})
```

---

## ❌ 已下线接口

| 接口 | 原因 | 下线时间 |
|------|------|---------|
| 🤖 Reddit `/api_reddit.php` | 国内被墙，25秒超时后仅返回fallback数据 | 2026-05-01 |
| 🎭 ArtPexels `/api_artpexels.php` | 响应10秒+，仅fallback数据，无实际价值 | 2026-05-01 |
| 🏰 Wallhaven `/api_wallhaven.php` | 响应5秒+，仅fallback数据，需API Key | 2026-05-01 |

> PHP文件仍保留在服务器，如配置代理或API Key后可重新启用。

---

## Flutter 接入示例

```dart
import 'package:dio/dio.dart';

final dio = Dio(BaseOptions(baseUrl: 'http://bz.wktyl.com'));

Future<List> fetchWallpapers({String source = 'unsplash', int page = 1, int limit = 20}) async {
  final r = await dio.get('/api_${source}.php', queryParameters: {'limit': limit, 'page': page});
  if (r.data['success'] == true) {
    return r.data['data'];
  }
  return [];
}

// 使用
final items = await fetchWallpapers(source: 'unsplash', page: 1);
for (var item in items) {
  final title = item['resource_info']['title'];
  final imgUrl = item['media']['image_url'];
  final thumb = item['media']['thumbnail_url'];
  final resolution = item['media']['resolution'];
}
```

## Swift 接入示例

```swift
func fetchWallpapers(source: String = "unsplash", page: Int = 1) async throws -> [[String: Any]] {
    let url = URL(string: "http://bz.wktyl.com/api_\(source).php?limit=20&page=\(page)")!
    let (data, _) = try await URLSession.shared.data(from: url)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    if json["success"] as? Bool == true {
        return json["data"] as! [[String: Any]]
    }
    return []
}
```