Pan-Relay API
v1.0 REST
小程序 / APP / 第三方平台接入方案

Pan-Relay 开发者 API 接口指南

提供两步走中转逻辑:从资源检索 (包含纯站长收益库 scope=own 与全网聚合) 到自动化转存替换专属链接 (POST /api/v1/transfer),并内置原生 12 大网盘免登录测活与防空链拦截。

Base URL: /api/v1 Auth: X-API-Key OpenAPI Spec: GET /api/v1/docs?format=json

1. 两步走收益接入闭环

步骤 1 · 检索 GET /api/v1/search

查询全网或站长收益资源

支持指定 scope=own 仅检索站长已有收益库(0 服务器开销、毫秒级响应、结果均为站长专属收益链),或 scope=all 全网聚合检索。

输入: 关键词 (keyword)
步骤 2 · 转存沉淀 POST /api/v1/transfer

替换为站长专属网盘收益链接

用户点击获取资源时,将原始链接提交给转存接口。系统默认执行前置免登录测活检查,自动将有效资源保存到站长云盘并生成站长专属分享链接,杜绝死链与空链接入库。

输入: 原始 url + 密钥
原生免登录网盘链接测活保障 (覆盖夸克、百度、阿里、UC、迅雷、123盘、天翼、115、移动云盘、联通云盘、悟空网盘、光鸭云盘 12 大网盘)

无需登录第三方网盘即可快速检测分享链接的真实有效性、是否需要提取码、以及内部包含的文件总数。步骤 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 核心节点规范

GET /api/v1/status
基础概览 · 服务运行状态与 API 模式

检查后端服务连通性,并获取当前开启的服务模式及可用端点列表。无需鉴权。

Response Example (JSON):
{
  "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"
  }
}
GET /api/v1/search
步骤 1 · 聚合资源搜索 (支持原生测活)

根据关键词搜索库内收益资源或全网聚合资源。

参数 类型 必填 说明
keyword string 是 搜索关键词,例如:黑神话
scope string 否 own: 仅检索站长专属收益库; all: 全网聚合搜索。默认按后台配置。
cloud_name string 否 筛选网盘平台,支持全称或常见简称/别名(如 百度、阿里、夸克、quark、115、123、uc 等),支持单个或逗号分隔多个 (如:夸克,百度 或 夸克网盘,百度网盘)
limit int 否 返回结果条数限制,默认 100
Response Example (JSON):
{
  "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 为兼容别名。

GET /api/v1/search/stream 强烈推荐 (UI / 前端首选)
步骤 1 (SSE) · 0等待秒级实时流式打字机推送

使用 Server-Sent Events (SSE) 协议实时流式返回搜索结果。强烈推荐 Web 前端、小程序、App 用户交互界面优先使用此接口,首屏数据几十毫秒推送,避免同步接口等待全网爬虫导致的数秒卡顿。请求参数与 GET /api/v1/search 完全一致(包含 keyword 必填、cloud_name、limit、scope)。

SSE Stream Format:
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}
POST /api/v1/transfer
步骤 2 · 替换为站长收益链接 (前置测活防护)

将原始分享链接转存至站长云盘,生成站长专属收益链接。默认前置测活校验(空资源、违规或失效链接直接返回 HTTP 422 拒绝转存)。

Body 属性 类型 必填 说明
url string 是 待中转的原始网盘分享链接
title string 否 资源标题 (默认:未命名资源)
netdisk_name string 否 网盘名称 (如:夸克网盘、百度网盘,留空智能推断)
password string 否 原始链接提取码 (若有)
skip_check bool 否 是否跳过前置免登录测活检查,默认 false。保持 false 时异常链接返回 HTTP 422 拦截
Request Body (JSON):
{
  "url": "https://pan.quark.cn/s/raw_public_123",
  "title": "电影名称",
  "netdisk_name": "夸克网盘"
}
Response Example (JSON):
{
  "success": true,
  "message": "资源转换与链接生成成功",
  "data": {
    "url": "https://pan.quark.cn/s/my_relay_link_999",
    "mode": "temp_share",
    "netdisk_name": "夸克网盘"
  }
}
POST /api/v1/link/check
实用工具 · 网盘免登录测活 (单条/批量)

原生探测 12 大网盘(夸克、百度、阿里、UC、迅雷、123盘、天翼、115、移动云盘、联通云盘、悟空网盘、光鸭云盘),免登录实时解析资源有效性、提取码状态、以及内部文件数量。

Single Check Request:
{
  "url": "https://pan.quark.cn/s/raw_public_123",
  "password": "",
  "disk_type": "夸克网盘",
  "refresh": false
}
Single Check Response:
{
  "success": true,
  "mode": "single",
  "data": {
    "url": "https://pan.quark.cn/s/raw_public_123",
    "state": "ok",
    "summary": "链接有效",
    "file_count": 5,
    "disk_type": "夸克网盘"
  }
}
GET /api/v1/resources
资产管理 · 收益资源库列表

分页查询库内已保存的收益资产列表。支持参数:page (默认 1)、page_size (默认 10)、search (可选搜索词)。

Response Example (JSON):
{
  "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
Response
· Ready
// 点击“发送测试请求”在此查看真实 HTTP 响应数据