网盘开放 API 文档

面向开发者的高速外链网盘开放接口。所有接口地址自动适配当前域名，可直接复制使用。

鉴权说明

所有请求必须携带密钥，二选一（推荐请求头）

公共参数与返回结构

公共请求参数

统一返回结构

限制与白名单

• 单文件上限：默认 500MB（受服务器配置限制）
• 上传频率：每分钟 5 次（upload/update 共享）
• 禁止脚本：php/jsp/asp/sh/py 等可执行文件拦截
• 列表最多返回 500 条

推荐调用流程

外链永久不变，更新文件不会改变下载地址，适合软件更新、图床场景。

1. 注册账号 POST FormData 调试

创建新用户，需后台开启 API 注册开关。

请求参数

请求示例

curl --location --request POST '{{base}}?action=register' \
--header 'X-Api-Key: {{API_KEY}}' \
--form 'username="demo"' \
--form 'password="123456"' \
--form 'member_days="30"' \
--form 'email="user@example.com"' \
--form 'email_code="123456"'

<?php
$ch = curl_init('{{base}}?action=register');
curl_setopt_array($ch,[
  CURLOPT_POST=>true,
  CURLOPT_RETURNTRANSFER=>true,
  CURLOPT_HTTPHEADER=>['X-Api-Key: {{API_KEY}}'],
  CURLOPT_POSTFIELDS=>['username'=>'demo','password'=>'123456','member_days'=>30,'email'=>'user@example.com','email_code'=>'123456']
]);
var_dump(json_decode(curl_exec($ch),true));

let fd=new FormData();
fd.append('username','demo');
fd.append('password','123456');
fd.append('member_days','30');
fd.append('email','user@example.com');
fd.append('email_code','123456');
fetch('{{base}}?action=register',{
  method:'POST',
  headers:{'X-Api-Key':'{{API_KEY}}'},
  body:fd
}).then(res=>res.json()).then(console.log);

成功返回

{
  "code":0,
  "msg":"注册成功",
  "data":{"id":1,"username":"demo","email":"user@example.com","member_days":30,"member_expire":"2026-10-28 09:00:00","is_member":true}
}

2. 注册邮箱验证码 POST 调试

向注册用邮箱发送 6 位验证码（10 分钟有效），配合 register 接口的 email + email_code 参数完成邮箱验证注册。

请求参数

成功返回

{
  "code":0,
  "msg":"验证码已发送至邮箱，10 分钟内有效，请注意查收",
  "data":{"email":"user@example.com","purpose":"register"}
}

3. 上传文件 POST FormData 调试

上传文件，返回永久外链与文件 Token。

参数

成功返回

{
  "code":0,
  "msg":"上传成功",
  "data":{
    "token":"xxx",
    "link":"https://xxx/download.php?token=xxx"
  }
}

4. 更新替换文件 POST FormData 调试

使用新文件覆盖原有文件，文件token、下载外链永久不变。

请求参数

请求示例

curl --location --request POST '{{base}}?action=update' \
--header 'X-Api-Key: {{API_KEY}}' \
--form 'username="demo"' \
--form 'token="file_xxxx"' \
--form 'file=@"/本地路径/新文件.jpg"'

<?php
$ch = curl_init('{{base}}?action=update');
$fd = [
    'username' => 'demo',
    'token' => 'file_xxxx',
    'file' => new CURLFile('/本地路径/新文件.jpg')
];
curl_setopt_array($ch,[
  CURLOPT_POST=>true,
  CURLOPT_RETURNTRANSFER=>true,
  CURLOPT_HTTPHEADER=>['X-Api-Key: {{API_KEY}}'],
  CURLOPT_POSTFIELDS=>$fd
]);
var_dump(json_decode(curl_exec($ch),true));

let fd=new FormData();
fd.append('username','demo');
fd.append('token','file_xxxx');
fd.append('file',fileInput.files[0]);
fetch('{{base}}?action=update',{
  method:'POST',
  headers:{'X-Api-Key':'{{API_KEY}}'},
  body:fd
}).then(res=>res.json()).then(console.log);

成功返回

{
  "code":0,
  "msg":"文件替换成功",
  "data":{
    "token":"file_xxxx",
    "link":"https://xxx/download.php?token=file_xxxx",
    "size":1048576,
    "mtime":1758888888
  }
}

5. 编辑文件属性 POST FormData 调试

修改文件名、文件可见性、下载提取码，不改动文件本体。

请求参数

请求示例

curl --location --request POST '{{base}}?action=edit' \
--header 'X-Api-Key: {{API_KEY}}' \
--form 'username="demo"' \
--form 'token="file_xxxx"' \
--form 'name="newfile.jpg"' \
--form 'is_public="1"'

<?php
$ch = curl_init('{{base}}?action=edit');
$fd = [
    'username' => 'demo',
    'token' => 'file_xxxx',
    'name' => 'newfile.jpg',
    'is_public' => '1'
];
curl_setopt_array($ch,[
  CURLOPT_POST=>true,
  CURLOPT_RETURNTRANSFER=>true,
  CURLOPT_HTTPHEADER=>['X-Api-Key: {{API_KEY}}'],
  CURLOPT_POSTFIELDS=>$fd
]);
var_dump(json_decode(curl_exec($ch),true));

let fd=new FormData();
fd.append('username','demo');
fd.append('token','file_xxxx');
fd.append('name','newfile.jpg');
fd.append('is_public','1');
fetch('{{base}}?action=edit',{
  method:'POST',
  headers:{'X-Api-Key':'{{API_KEY}}'},
  body:fd
}).then(res=>res.json()).then(console.log);

成功返回

{
  "code":0,
  "msg":"属性修改成功",
  "data":{
    "token":"file_xxxx",
    "name":"newfile.jpg",
    "is_public":1,
    "has_password":0
  }
}

6. 删除文件 POST FormData 调试

永久删除文件及数据库记录，操作不可恢复。

请求参数

请求示例

curl --location --request POST '{{base}}?action=delete' \
--header 'X-Api-Key: {{API_KEY}}' \
--form 'username="demo"' \
--form 'token="file_xxxx"'

<?php
$ch = curl_init('{{base}}?action=delete');
$fd = [
    'username' => 'demo',
    'token' => 'file_xxxx'
];
curl_setopt_array($ch,[
  CURLOPT_POST=>true,
  CURLOPT_RETURNTRANSFER=>true,
  CURLOPT_HTTPHEADER=>['X-Api-Key: {{API_KEY}}'],
  CURLOPT_POSTFIELDS=>$fd
]);
var_dump(json_decode(curl_exec($ch),true));

let fd=new FormData();
fd.append('username','demo');
fd.append('token','file_xxxx');
fetch('{{base}}?action=delete',{
  method:'POST',
  headers:{'X-Api-Key':'{{API_KEY}}'},
  body:fd
}).then(res=>res.json()).then(console.log);

成功返回

{
  "code":0,
  "msg":"文件已删除",
  "data":{
    "token":"file_xxxx"
  }
}

7. 获取用户文件列表 GET POST 调试

获取用户最近 500 条文件信息、外链、大小、下载次数；owner_is_member 表示上传者是否会员（决定该用户全部外链是否限速）。

请求参数

成功返回

{
  "code":0,
  "msg":"ok",
  "data":{
    "username":"demo",
    "owner_is_member":1,
    "count":2,
    "files":[
      {
        "id":101,
        "name":"产品手册.pdf",
        "ext":"pdf",
        "size":1048576,
        "size_text":"1.00 MB",
        "token":"a1b2c3d4e5f67890a1b2c3d4e5f67890",
        "link":"https://xxx/download.php?token=a1b2c3d4e5f67890a1b2c3d4e5f67890",
        "is_public":1,
        "has_password":0,
        "downloads":12,
        "created_at":"2026-09-01 10:20:30"
      },
      {
        "id":100,
        "name":"壁纸.png",
        "ext":"png",
        "size":524288,
        "size_text":"512.00 KB",
        "token":"f6e5d4c3b2a19988f6e5d4c3b2a19988",
        "link":"https://xxx/download.php?token=f6e5d4c3b2a19988f6e5d4c3b2a19988",
        "is_public":0,
        "has_password":1,
        "downloads":3,
        "created_at":"2026-08-30 18:00:00"
      }
    ]
  }
}

跨域（CORS）与用户级 Token 机制 v12+

v12 起开放 API 支持浏览器跨域调用与用户身份凭证，外部网页 / APP / 小程序均可直连。

跨域说明

• 默认响应 Access-Control-Allow-Origin: *，允许所有来源跨域访问
• 预检请求（OPTIONS）直接返回 204，无需携带 APIKey
• 如需限制来源：在数据库 settings 表写入 api_cors_origin 键，值为允许的域名（如 https://app.example.com）
• 允许的请求方式：GET / POST / OPTIONS；允许的头：Content-Type、X-Api-Key、Authorization

用户级 Token

• 由 login 接口返回，格式为 用户名.32位签名，长期有效
• 传递方式：参数 token 或 请求头 Authorization: Bearer 用户名.签名
• 无状态设计：不依赖 Cookie / Session，天然适配 APP 与服务端调用
• 用户修改密码或管理员更换 APIKey 后，旧 token 自动全部失效（需重新 login）
• 文件接口（upload / update / edit / delete / list）沿用 username 定位；用户本人操作接口（member_status / pay_create / orders / space）一律使用 token

接口分类速查

8. 用户登录 POST 调试

账号密码登录，返回用户级 token（供 member_status / pay_create / orders / space 使用）。

请求参数

成功返回

{
  "code":0,
  "msg":"登录成功",
  "data":{
    "token":"demouser.9f2c6b8a1d4e7f0a3b5c8d2e6f9a1b4c",
    "id":8,
    "username":"demouser",
    "is_member":true,
    "member_expire":"2026-12-31 23:59:59",
    "token_tip":"token 长期有效；修改密码或更换 APIKey 后失效，需重新登录"
  }
}

9. 查询会员状态 POST 调试

查询当前用户是否为会员、到期时间与剩余时长。

请求参数

成功返回

{
  "code":0,
  "msg":"ok",
  "data":{
    "username":"demouser",
    "is_member":true,
    "member_expire":"2026-12-31 23:59:59",
    "member_days_left":94,
    "member_seconds_left":8121600,
    "member_expire_ts":1798761599
  }
}

10. 会员套餐与价格 GET POST 调试

返回全部已启用的会员套餐（价格 / 天数 / 附加容量），无需用户身份。

请求参数

成功返回

{
  "code":0,
  "msg":"ok",
  "data":{
    "count":3,
    "plans":[
      {"id":1,"name":"月度会员","price":"9.90","days":30,"space_mb":5120},
      {"id":2,"name":"季度会员","price":"25.00","days":90,"space_mb":20480},
      {"id":3,"name":"年度会员","price":"88.00","days":365,"space_mb":102400}
    ],
    "space_base_mb":100
  }
}

11. 远程发起会员支付 POST 调试

选定套餐与支付方式创建订单，返回支付页地址 pay_url，适合 APP / 外部客户端远程下单。

请求参数

成功返回

{
  "code":0,
  "msg":"订单创建成功",
  "data":{
    "order_no":"20260928153012A1B2C3D4",
    "plan_name":"月度会员",
    "plan_days":30,
    "amount":"9.90",
    "pay_type":"epay_alipay",
    "pay_url":"https://xxx/pay/api_pay.php?no=20260928153012A1B2C3D4&token=demouser.9f2c...",
    "pay_tip":"在系统浏览器或 APP 内嵌 WebView 中打开 pay_url 完成支付；支付结果可通过 action=orders 查询"
  }
}

12. 我的支付订单查询 POST 调试

查询当前用户最近 20 条会员订单（含支付状态）。

请求参数

成功返回

{
  "code":0,
  "msg":"ok",
  "data":{
    "username":"demouser",
    "count":2,
    "orders":[
      {
        "order_no":"20260928153012A1B2C3D4",
        "plan_name":"月度会员",
        "plan_days":30,
        "amount":"9.90",
        "pay_type":"epay_alipay",
        "status":1,
        "status_text":"已支付",
        "created_at":"2026-09-28 15:30:12",
        "paid_at":"2026-09-28 15:31:40"
      },
      {
        "order_no":"20260920101500E5F6A7B8",
        "plan_name":"年度会员",
        "plan_days":365,
        "amount":"88.00",
        "pay_type":"alipay",
        "status":0,
        "status_text":"待支付",
        "created_at":"2026-09-20 10:15:00",
        "paid_at":""
      }
    ]
  }
}

13. 找回密码 · 发送验证码 POST 调试

向账号绑定邮箱发送 6 位验证码（10 分钟有效），需后台已配置 SMTP。

请求参数

成功返回

{
  "code":0,
  "msg":"验证码已发送，请查收邮件（注意垃圾箱）",
  "data":{"email":"user@example.com"}
}

14. 找回密码 · 重置新密码 POST 调试

校验邮箱验证码并设置新密码；成功后旧 token 全部失效。

请求参数

成功返回

{
  "code":0,
  "msg":"密码重置成功，请使用新密码重新登录",
  "data":{"username":"demouser"}
}

15. 公开文件列表 GET POST 调试

全站公开文件的分页列表（无需用户身份），可直接做成分享广场页。

请求参数

成功返回

{
  "code":0,
  "msg":"ok",
  "data":{
    "page":1,
    "psize":20,
    "total":128,
    "page_total":7,
    "files":[
      {
        "id":66,
        "name":"产品手册.pdf",
        "ext":"pdf",
        "size":1048576,
        "size_text":"1.00 MB",
        "token":"a1b2c3...",
        "link":"https://xxx/download.php?token=a1b2c3...",
        "has_password":0,
        "owner_is_member":1,
        "downloads":12,
        "created_at":"2026-09-01 10:20:30"
      }
    ]
  }
}

16. 站点公告 GET POST 调试

返回站点公告（管理员在后台「公告管理」页维护，含开关与文字颜色），与前台首页公告栏同一数据源。

请求参数

成功返回

{
  "code":0,
  "msg":"ok",
  "data":{
    "site_name":"水彩云盘",
    "content":"系统将于本周日凌晨 2-4 点维护升级，期间暂停上传服务。",
    "has_ann":1,
    "notice_enabled":1,
    "notice_color":"#ff0000"
  }
}

17. 上传限制 GET POST 调试

返回上传大小上限、允许的文件类型与频率限制，客户端可据此做前置校验；另含下载限速配置。

请求参数

成功返回

{
  "code":0,
  "msg":"ok",
  "data":{
    "max_upload_mb":500,
    "allowed_exts":"zip,rar,jpg,png,mp4,pdf",
    "allowed_exts_array":["zip","rar","jpg","png","mp4","pdf"],
    "upload_per_min":5,
    "php_upload_max_filesize":"512M",
    "php_post_max_size":"512M",
    "normal_speed":512,
    "member_speed":0,
    "speed_tip":"v13 起按上传者身份限速：会员上传的文件任何人下载均不限速（member_speed），普通用户上传的按 normal_speed 限速；0 表示不限速"
  }
}

18. 我的容量 POST 调试

查询当前用户的容量配额、已用与剩余（基础 + 会员赠送容量）。

请求参数

成功返回

{
  "code":0,
  "msg":"ok",
  "data":{
    "username":"demouser",
    "unlimited":0,
    "base_mb":100,
    "bonus_mb":5120,
    "quota_mb":5220,
    "used_mb":326.5,
    "remain_mb":4893.5,
    "used_bytes":342360064,
    "quota_bytes":5474304000,
    "percent":6.3,
    "used_text":"326.50 MB"
  }
}

开发注意事项

• action 放在 URL 参数，业务参数全部 FormData
• 必须判断 code===0 才算成功
• link 为完整外链，无需拼接域名
• 更新文件不会改变外链，适合长期使用
• 禁止前端硬编码 APIKey
• v12 起支持跨域（CORS）：默认全来源放行，可在数据库 settings 表 api_cors_origin 键自定义来源域名
• 用户级 token 通过 login 获取，无状态长期有效；修改密码或更换 APIKey 后自动失效
• pay_create 返回的 pay_url 需在系统浏览器 / APP 内嵌 WebView 中打开完成支付，结果用 orders 查询
• plans / public_files / announcement / upload_limit 无需 username 参数（GET 直调）
• v14 新增热更新（v14.2 起固定单项目：后台仅维护一条当前版本记录，无新增 / 删除）：update_check 检查更新（latest / list / has_update / force_update，type 区分补丁包与完整包，force=1 表示强制更新不可跳过），update_hit 记录下载次数

19. 热更新检查 GET POST 调试

客户端版本检查更新：返回最新版本（latest）、是否需要更新与是否强制更新。后台「热更新」页为固定单项目模式（仅维护一条当前版本记录，无新增 / 删除），latest 即该唯一项目，list 为单元素数组。

请求参数

成功返回

{
  "code":0,
  "msg":"ok",
  "data":{
    "current_ver":"1.0.0",
    "has_update":1,
    "force_update":1,
    "latest":{
      "id":3,
      "ver":"1.0.1",
      "type":"patch",
      "type_text":"补丁包",
      "force":1,
      "force_text":"强制更新",
      "url":"https://xxx/patch_1.0.1.zip",
      "note":"修复若干问题，优化下载速度",
      "weight":100,
      "hits":12,
      "created_at":"2026-10-02 16:30:00"
    },
    "list":[...],
    "tip":"type=patch 为增量补丁包、type=full 为完整安装包；latest 为权重最高的更新项，has_update 按 version_compare 与传入 ver 比较得出；force=1 表示强制更新（客户端不可跳过），force_update 为 latest 的强制标记"
  }
}

20. 更新下载统计 GET POST 调试

客户端开始下载更新包时调用一次，对应更新项的下载次数（hits）+1。

请求参数

成功返回

{
  "code":0,
  "msg":"已记录一次下载",
  "data":{
    "id":3,
    "ver":"1.0.1",
    "hits":13
  }
}