接口总览

接口分区

前缀	使用者	鉴权方式
/v1/*	游客和公开页面	无登录，部分操作需要验证码或设备校验
/auth/v1/*	已登录终端用户	用户会话
/admin/v1/*	管理员	独立管理员会话与角色校验
/open/*	自动化脚本、站群和外部 worker	独立 API Token 请求头

管理员会话和终端用户会话不是同一套。登录后台不代表可以直接调用 /auth/v1，反之亦然。

通用响应

矩阵盘常见响应信封：

{
  "code": 200,
  "msg": "请求成功",
  "data": {}
}

业务成功码是 200。调用方应同时检查 HTTP 状态和响应中的 code，不要把 code: 0 当成成功。

分页与排序

列表常用：

• page：从 1 开始；
• size：每页数量，接口会限制最大值；
• by_<field>=asc|desc：按字段排序；
• with_<relation>=true：请求允许的关联信息。

不同接口返回形状可能是 { list, total } 或直接数组，应按当前接口说明处理，不能用一套未经核对的解析器强行统一。

网盘类型

接口中的主要类型包括：

BDY  ALY  QUARK  XUNLEI  UC  115

部分开放导入能力还会使用 MAGNET 和 ED2K。不要擅自改成小写或中文；展示层可以显示中文名称，接口值保持约定。

主搜索接口

公开搜索使用 POST /v1/search/disk 和 JSON 请求体，而不是把全部筛选写入 URL。示例：

POST /v1/search/disk
Content-Type: application/json

{
  "q": "学习资料",
  "type": "QUARK",
  "page": 1,
  "size": 15,
  "format": [".pdf"],
  "order": "create_desc"
}

公开页面还会根据站点配置使用验证码、搜索票据、设备挑战和访问限制。自动化调用不能通过伪造浏览器字段绕过这些规则。

接口文档和版本

接口可能随版本增加字段，但已发布路径和关键字段会尽量保持兼容。集成前先确认目标矩阵盘版本，并在测试实例验证成功、权限不足、参数错误、频率限制和服务故障等分支。

令牌传递方式见接口鉴权与安全。