📚 API 文档

网盘搜搜提供公开 API，支持 AI Agent、爬虫和第三方应用调用。匿名访问按 IP 限流，配置 Token 后可获更高配额。

基础信息

API 地址https://s.zbo.hk/api
请求方式GET / POST
鉴权方式可选 Token（匿名可访问，Token 可获更高配额）
限流策略匿名 60 次/分钟（按 IP），Token 用户 300 次/分钟（可配置）
Token 传递Authorization: Bearer <token> 或 ?token=<token>
限流响应头X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset
响应格式JSON

响应格式

所有接口返回统一的 JSON 格式：

{
  "code": 0,        // 0 表示成功，非 0 表示失败
  "message": "操作成功",  // 提示信息
  "data": { ... }   // 响应数据
}

接口列表

GET/api/resources

获取资源列表，支持分页、排序、搜索和分类筛选

参数

page页码，默认 1
pageSize每页数量，默认 12
sort排序方式：hot（热门）或 new（最新），默认 hot
keyword搜索关键词（可选）
categoryId分类 ID（可选）
status后台用：按状态筛选（pending/approved/rejected），前台仅返回 approved

调用示例

curl "https://s.zbo.hk/api/resources?page=1&pageSize=12&sort=hot"

响应示例

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "list": [
      {
        "id": 8,
        "title": "文档：2024考研英语真题及解析",
        "icon": "📋",
        "downloads": 3450,
        "category": { "id": 8, "name": "文档", "icon": "📋" },
        "cloudLinks": [...]
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 12
  }
}
GET/api/resources/:id

获取资源详情，包含所有网盘下载链接

调用示例

curl "https://s.zbo.hk/api/resources/8"

响应示例

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "resource": {
      "id": 8,
      "title": "文档：2024考研英语真题及解析",
      "downloads": 3450,
      "cloudLinks": [
        {
          "cloudType": "quark",
          "url": "https://pan.quark.cn/s/xxxxx",
          "extractionCode": null
        }
      ]
    },
    "related": [...]
  }
}
POST/api/resources/:id/download

记录资源下载行为（点击网盘链接时调用，用于统计下载量）

调用示例

curl -X POST "https://s.zbo.hk/api/resources/8/download"
GET/api/search

搜索资源，自动记录搜索历史

参数

keyword搜索关键词（必填）
page页码，默认 1
pageSize每页数量，默认 12

调用示例

curl "https://s.zbo.hk/api/search?keyword=Python&page=1"
GET/api/resources/hot

获取热门资源列表

参数

limit返回数量，默认 5

调用示例

curl "https://s.zbo.hk/api/resources/hot?limit=5"
GET/api/resources/recent

获取最近收录的资源

参数

limit返回数量，默认 6

调用示例

curl "https://s.zbo.hk/api/resources/recent?limit=6"
GET/api/search/hot-keywords

获取热门搜索词

参数

limit返回数量，默认 10

调用示例

curl "https://s.zbo.hk/api/search/hot-keywords?limit=10"
GET/api/categories

获取所有资源分类列表

调用示例

curl "https://s.zbo.hk/api/categories"
GET/api/cloud-disks/active

获取启用的网盘类型列表

调用示例

curl "https://s.zbo.hk/api/cloud-disks/active"
GET/api/config/public

获取站点公开配置信息（站点名、密码开关、二维码、提示文案等）

调用示例

curl "https://s.zbo.hk/api/config/public"
POST/api/config/validate-password

验证下载密码是否正确（站点开启密码验证时使用，前端进入详情页下载时调用）

请求体

password下载密码（必填）

调用示例

curl -X POST "https://s.zbo.hk/api/config/validate-password" \
  -H "Content-Type: application/json" \
  -d '{"password": "8888"}'

响应示例

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "valid": true
  }
}
POST/api/tokens/validate

验证 API Token 有效性（调用方可自测 Token 状态与配额）

请求体

token要验证的 Token（必填）

调用示例

curl -X POST "https://s.zbo.hk/api/tokens/validate" \
  -H "Content-Type: application/json" \
  -d '{"token": "sk_xxxxxxxx"}'

响应示例

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "valid": true,
    "name": "测试 Token",
    "rateLimit": 300,
    "usageCount": 12,
    "lastUsedAt": "2026-07-27T10:00:00.000Z"
  }
}
POST/api/reports

提交资源失效反馈

请求体

resourceId资源 ID（必填）
cloudType网盘类型：baidu/quark/mobile/xunlei（可选）
reason反馈原因：link_invalid / wrong_resource / extraction_code_error / other

调用示例

curl -X POST "https://s.zbo.hk/api/reports" \
  -H "Content-Type: application/json" \
  -d '{"resourceId": 8, "cloudType": "quark", "reason": "link_invalid"}'
GET/api/submit/captcha

获取提交资源用的验证码（算术题，公开提交时使用）

调用示例

curl "https://s.zbo.hk/api/submit/captcha"

响应示例

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "captchaId": "1785048770217-aifn09gh",
    "question": "8 × 8 = ?",
    "expiresIn": 300
  }
}
POST/api/submit

公开提交资源（提交后进入待审核队列，审核通过后前台可见）

请求体

captchaId验证码 ID（必填，从 /api/submit/captcha 获取）
captchaAnswer验证码答案（必填，数字）
title资源标题（必填）
categoryId分类 ID（可选）
icon资源图标（可选，默认 📁）
submitterName提交者昵称（可选）
cloudLinks网盘链接数组（必填，至少 1 个），每项含 cloudType/url/extractionCode

调用示例

curl -X POST "https://s.zbo.hk/api/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "captchaId": "1785048770217-aifn09gh",
    "captchaAnswer": 64,
    "title": "示例资源标题",
    "submitterName": "热心网友",
    "cloudLinks": [
      {"cloudType": "baidu", "url": "https://pan.baidu.com/s/xxxxx", "extractionCode": "8888"}
    ]
  }'
GET/api/health

健康检查接口

调用示例

curl "https://s.zbo.hk/api/health"
GET/api/tvbox/software

获取 TVBox 软件列表（含每个软件的网盘下载链接）

调用示例

curl "https://s.zbo.hk/api/tvbox/software"

响应示例

{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "TvBox Q版",
      "icon": "📺",
      "description": "TvBox原版Q系列版本",
      "sortOrder": 1,
      "enabled": true,
      "links": [
        { "cloudType": "quark", "url": "https://pan.quark.cn/s/xxxxx", "extractionCode": null }
      ]
    }
  ]
}
GET/api/tvbox/interfaces

获取 TVBox 接口列表（JSON 接口 URL，配置到 TvBox 软件中）

参数

category分类筛选（可选）：preferred(优选) 或 other(其他)

调用示例

curl "https://s.zbo.hk/api/tvbox/interfaces?category=preferred"

响应示例

{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "王二小",
      "description": "混合线路，以网盘(4K)为主",
      "url": "https://9280.kstore.vip/newwex.json",
      "category": "preferred",
      "status": "active",
      "latency": 109
    }
  ]
}
GET/api/tvbox/sites

获取 TVBox 资源站点导航列表

调用示例

curl "https://s.zbo.hk/api/tvbox/sites"

响应示例

{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "鸭先知",
      "url": "https://www.yxzhi.com/hz/hzxl",
      "description": "TvBox系列软件长期更新"
    }
  ]
}