开发接入

WebDAV / API Token

第三方客户端挂载网盘，以及 API 上传下载文件的使用说明。

WebDAV / API Token 使用文档

创建 Token

进入「工具中心」点击「开发者平台」，或直接访问 /open/webdav-api。在「WebDAV / API Token」页面点击「创建 Token」。Token 创建后只显示一次，请立即保存。

WebDAV 连接

服务器地址：工具中心显示的 WebDAV 地址，通常为 `/webdav`
Windows 网络位置地址：`https://pan.yunxzi.cn/webdav/`
用户名：账号名、邮箱或手机号均可，用于 WebDAV 客户端显示
密码：创建后的 API Token

WebDAV 支持列目录、下载、上传、创建文件夹、删除到回收站等常用操作。

> WebDAV 使用 Basic Auth，服务端校验的是密码位置的 API Token。用户名用于兼容客户端显示。

Windows 添加网络位置

Windows 文件资源管理器中选择「添加网络位置」，地址填写：

https://pan.yunxzi.cn/webdav/

建议保留末尾斜杠。弹出登录框后：

用户名填写账号名、邮箱或手机号。
密码填写 API Token。

如果提示「输入的文件夹无效」，请确认地址包含 /webdav/，并确认 Token 未撤销。

HTTP API 认证

所有 API 请求使用 Bearer Token：

curl -H "Authorization: Bearer 你的 API Token" "https://pan.yunxzi.cn/api/files?path="

常用 API

接口表：

列出目录：`GET /api/files?path=`，`path` 为空表示根目录。
下载文件：`GET /api/files/{path}`，路径为文件在网盘中的相对路径。
获取下载直链：`GET /api/files/{path}?direct_download=1`，返回 1 小时有效的云存储签名 URL。
获取元数据：`GET /api/files/{path}?meta=1` 或 `POST /api/files` 携带 `action=metadata`。
获取缩略图：`GET /api/files/{path}?thumbnail=1`，图片和视频返回 JPEG 缩略图。
上传文件：`PUT /api/files/{path}`，请求体为文件二进制内容。
表单上传：`POST /api/files`，提交 `action=upload`、`path` 和 `file`。
分片直传：`POST /api/files`，依次调用 `init_direct_upload`、`get_direct_upload_part`、`complete_direct_upload`。
创建文件夹：`POST /api/files`，提交 `action=create_folder` 和 `path=docs`。
重命名：`POST /api/files`，提交 `action=rename`、`path` 和 `name`。
移动：`POST /api/files`，提交 `action=move`、`path` 和 `destination`。
复制：`POST /api/files`，提交 `action=copy`、`path`、`destination`，可选 `name`。
保存描述：`POST /api/files`，提交 `action=save_description`、`path` 和 `description`。
切换收藏：`POST /api/files`，提交 `action=toggle_favorite` 和 `path`。
恢复回收站项目：`POST /api/files`，提交 `action=restore` 和 `path`。
删除文件或文件夹：`DELETE /api/files/{path}`，删除进入回收站。

列出目录：

curl -H "Authorization: Bearer 你的 API Token" "https://pan.yunxzi.cn/api/files?path=docs"

上传文件：

curl -X PUT -H "Authorization: Bearer 你的 API Token" --data-binary @local.txt "https://pan.yunxzi.cn/api/files/docs/local.txt"

下载文件：

curl -L -H "Authorization: Bearer 你的 API Token" "https://pan.yunxzi.cn/api/files/docs/local.txt" -o local.txt

获取下载直链：

curl -H "Authorization: Bearer 你的 API Token" "https://pan.yunxzi.cn/api/files/docs/local.txt?direct_download=1"

获取元数据：

curl -H "Authorization: Bearer 你的 API Token" "https://pan.yunxzi.cn/api/files/docs/local.txt?meta=1"

获取缩略图：

curl -L -H "Authorization: Bearer 你的 API Token" "https://pan.yunxzi.cn/api/files/photos/a.jpg?thumbnail=1" -o thumb.jpg

创建文件夹：

curl -X POST -H "Authorization: Bearer 你的 API Token" -F "action=create_folder" -F "path=docs" "https://pan.yunxzi.cn/api/files"

删除文件或文件夹：

curl -X DELETE -H "Authorization: Bearer 你的 API Token" "https://pan.yunxzi.cn/api/files/docs/local.txt"

重命名、移动和复制：

curl -X POST -H "Authorization: Bearer 你的 API Token" -H "Content-Type: application/json" -d '{"action":"rename","path":"docs/local.txt","name":"readme.txt"}' "https://pan.yunxzi.cn/api/files"

curl -X POST -H "Authorization: Bearer 你的 API Token" -H "Content-Type: application/json" -d '{"action":"move","path":"docs/readme.txt","destination":"archive"}' "https://pan.yunxzi.cn/api/files"

curl -X POST -H "Authorization: Bearer 你的 API Token" -H "Content-Type: application/json" -d '{"action":"copy","path":"archive/readme.txt","destination":"docs","name":"copy.txt"}' "https://pan.yunxzi.cn/api/files"

描述、收藏和恢复：

curl -X POST -H "Authorization: Bearer 你的 API Token" -H "Content-Type: application/json" -d '{"action":"save_description","path":"docs/copy.txt","description":"接口写入的描述"}' "https://pan.yunxzi.cn/api/files"

curl -X POST -H "Authorization: Bearer 你的 API Token" -H "Content-Type: application/json" -d '{"action":"toggle_favorite","path":"docs/copy.txt"}' "https://pan.yunxzi.cn/api/files"

curl -X POST -H "Authorization: Bearer 你的 API Token" -H "Content-Type: application/json" -d '{"action":"restore","path":"docs/copy.txt"}' "https://pan.yunxzi.cn/api/files"

表单上传：

curl -X POST -H "Authorization: Bearer 你的 API Token" -F "action=upload" -F "path=docs" -F "file=@local.txt" "https://pan.yunxzi.cn/api/files"

安全说明

API Token 等同于第三方访问密码。创建后只显示一次；如 Token 泄露，请在开发者平台立即撤销并重新创建。

可运行 Demo

开发者平台提供多语言 Demo 源码，路径为 https://api.scywp.hw.yunxzi.cn/api/demo/webdav-api/。

支持语言：

PHP：`php-demo.php`
Python：`python_demo.py`
Java：`ApiDemo.java`
Node.js：`node-demo.mjs`
cURL：`curl-demo.sh`

Demo 覆盖列目录、创建文件夹、上传文件、下载文件、删除到回收站。运行前设置环境变量：

export PAN_API_TOKEN="你的 API Token"
export PAN_BASE_URL="https://pan.yunxzi.cn"

Token 管理

启用中的 Token 可以撤销。
已撤销的 Token 可以删除记录。
删除记录只清理列表展示，已撤销状态不会恢复。

文档中心