Pan-Relay 开发者 API 接口指南
提供两步走中转逻辑:从资源检索 (包含纯站长收益库 scope=own 与全网聚合) 到自动化转存替换专属链接 (POST /api/v1/transfer),并内置原生 12 大网盘免登录测活与防空链拦截。
1. 两步走收益接入闭环
查询全网或站长收益资源
支持指定 scope=own 仅检索站长已有收益库(0 服务器开销、毫秒级响应、结果均为站长专属收益链),或 scope=all 全网聚合检索。
替换为站长专属网盘收益链接
用户点击获取资源时,将原始链接提交给转存接口。系统默认执行前置免登录测活检查,自动将有效资源保存到站长云盘并生成站长专属分享链接,杜绝死链与空链接入库。
无需登录第三方网盘即可快速检测分享链接的真实有效性、是否需要提取码、以及内部包含的文件总数。步骤 2 转存默认自动拦截问题链接并返回 HTTP 422 状态码,或者通过独立接口 POST /api/v1/link/check 进行异步测活。
2. 接口安全鉴权 (`X-API-Key`)
为了保证网盘空间不被恶意刷爆,转存接口支持后台设置 API Key。当管理员配置了 Key 时,需要在 HTTP Header 或参数中带上凭证:
| 鉴权方式 | 位置 | 传递格式与示例 |
|---|---|---|
| X-API-Key 标头 (推荐) | HTTP Header | X-API-Key: <你的转存密钥> |
| Bearer Token 标头 | HTTP Header | Authorization: Bearer <你的转存密钥> |
| URL / Body 参数 | Query / Body | ?api_key=<你的转存密钥> 或 {"api_key": "xxx"} |
* 注:若管理后台“转存 API 鉴权密钥”未设置(保持留空),转存接口默认为公开可调状态。*
3. API 核心节点规范
/api/v1/status
检查后端服务连通性,并获取当前开启的服务模式及可用端点列表。无需鉴权。
{
"success": true,
"service": "pan-relay",
"version": "1.0.0",
"status": "healthy",
"api_mode": {
"api_only": false,
"enable_frontend": true,
"search_scope": "all",
"transfer_api_key": ""
},
"endpoints": {
"status": "/api/v1/status",
"search": "/api/v1/search",
"search_stream": "/api/v1/search/stream",
"transfer": "/api/v1/transfer",
"link_check": "/api/v1/link/check",
"resources": "/api/v1/resources",
"docs": "/api/v1/docs"
}
}
/api/v1/search
根据关键词搜索库内收益资源或全网聚合资源。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | string | 是 | 搜索关键词,例如:黑神话 |
| scope | string | 否 | own: 仅检索站长专属收益库; all: 全网聚合搜索。默认按后台配置。 |
| cloud_name | string | 否 | 筛选网盘平台,支持全称或常见简称/别名(如 百度、阿里、夸克、quark、115、123、uc 等),支持单个或逗号分隔多个 (如:夸克,百度 或 夸克网盘,百度网盘) |
| limit | int | 否 | 返回结果条数限制,默认 100 |
{
"success": true,
"scope": "all",
"total": 1,
"results": [
{
"title": "黑神话:悟空 高清原画合集",
"name": "黑神话:悟空 高清原画合集",
"share_link": "https://pan.quark.cn/s/raw_sample_123",
"url": "https://pan.quark.cn/s/raw_sample_123",
"cloud_name": "夸克网盘",
"drive_type": "quark",
"password": "",
"source": "hot",
"source_type": "api",
"source_display": "API",
"source_id": "example_api",
"source_name": "示例 API",
"datetime": "2026-10-17 12:30:00",
"description": "资源简介",
"cover_url": "https://example.com/cover.jpg",
"image": "https://example.com/cover.jpg",
"cover": "https://example.com/cover.jpg",
"metadata": {"category": "电影", "rating": 8.5}
}
]
}
资源对象还会返回 source_type、source_display、source_id、source_name 用于来源分类与溯源;按可用情况返回 datetime、description、cover_url(兼容别名 image/cover)和安全扩展字段 metadata。可选字段没有值时会省略。title/name、share_link/url 为兼容别名。
/api/v1/search/stream
强烈推荐 (UI / 前端首选)
使用 Server-Sent Events (SSE) 协议实时流式返回搜索结果。强烈推荐 Web 前端、小程序、App 用户交互界面优先使用此接口,首屏数据几十毫秒推送,避免同步接口等待全网爬虫导致的数秒卡顿。请求参数与 GET /api/v1/search 完全一致(包含 keyword 必填、cloud_name、limit、scope)。
data: {"type": "start", "keyword": "黑神话"}
data: {"type": "item", "data": {"title": "黑神话:悟空", "share_link": "https://pan.quark.cn/s/...", "cloud_name": "夸克网盘", "source_type": "telegram", "source_display": "TG", "source_id": "channel_id", "source_name": "频道名称", "datetime": "2026-10-17", "description": "资源简介", "cover_url": "https://example.com/cover.jpg"}}
data: {"type": "done", "total": 1}
/api/v1/transfer
将原始分享链接转存至站长云盘,生成站长专属收益链接。默认前置测活校验(空资源、违规或失效链接直接返回 HTTP 422 拒绝转存)。
| Body 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 待中转的原始网盘分享链接 |
| title | string | 否 | 资源标题 (默认:未命名资源) |
| netdisk_name | string | 否 | 网盘名称 (如:夸克网盘、百度网盘,留空智能推断) |
| password | string | 否 | 原始链接提取码 (若有) |
| skip_check | bool | 否 | 是否跳过前置免登录测活检查,默认 false。保持 false 时异常链接返回 HTTP 422 拦截 |
{
"url": "https://pan.quark.cn/s/raw_public_123",
"title": "电影名称",
"netdisk_name": "夸克网盘"
}
{
"success": true,
"message": "资源转换与链接生成成功",
"data": {
"url": "https://pan.quark.cn/s/my_relay_link_999",
"mode": "temp_share",
"netdisk_name": "夸克网盘"
}
}
/api/v1/link/check
原生探测 12 大网盘(夸克、百度、阿里、UC、迅雷、123盘、天翼、115、移动云盘、联通云盘、悟空网盘、光鸭云盘),免登录实时解析资源有效性、提取码状态、以及内部文件数量。
{
"url": "https://pan.quark.cn/s/raw_public_123",
"password": "",
"disk_type": "夸克网盘",
"refresh": false
}
{
"success": true,
"mode": "single",
"data": {
"url": "https://pan.quark.cn/s/raw_public_123",
"state": "ok",
"summary": "链接有效",
"file_count": 5,
"disk_type": "夸克网盘"
}
}
/api/v1/resources
分页查询库内已保存的收益资产列表。支持参数:page (默认 1)、page_size (默认 10)、search (可选搜索词)。
{
"success": true,
"data": {
"items": [
{
"id": 1,
"title": "黑神话:悟空 高清原画",
"cloud_name": "夸克网盘",
"share_link": "https://pan.quark.cn/s/my_relay_link_123",
"created_at": "2026-09-23 00:00:00"
}
],
"page": 1,
"page_size": 10,
"total": 1
}
}
4. 返回 JSON 数据字典
| 字段名 | 类型 | 含义与说明 |
|---|---|---|
| success | Boolean | true 成功;false 失败。 |
| scope | String | 搜索返回作用域:own (站长收益库) 或 all (全网并发)。 |
| health_state | String |
资源健康状态枚举:
ok 正常有效
bad 失效/违规/空文件
locked 需提取码
uncertain 探测超时或未知
|
| health_summary | String | 测活中文摘要,如“链接有效”、“分享链接无效:文件列表为空”。 |
| file_count | Integer | 分享链接内包含的文件总数。若为 0 则判定为空资源下架。 |
| code | String | 错误状态码标识:LINK_INVALID (422)、LINK_LOCKED (422)、INVALID_API_KEY (401)。 |
5. 多语言对接代码示例
# 步骤 1: 聚合搜索 (响应极快)
curl -X GET "http://localhost:5004/api/v1/search?keyword=黑神话"
# 步骤 2: 发起转存替换 (默认前置测活校验,若链接失效/空文件夹则返回 422 拦截)
curl -X POST "http://localhost:5004/api/v1/transfer" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"url": "https://pan.quark.cn/s/raw123", "title": "黑神话", "skip_check": false}'
6. 极简在线接口测试
Playground Console// 点击“发送测试请求”在此查看真实 HTTP 响应数据