Cloudreve API 文档

支持多家云存储的公有云文件系统

官方网站 · 在线体验 · English API Docs

📖 文档说明

本文档为 Cloudreve API 的中文版本，提供完整的接口说明、请求示例和响应格式。所有接口均基于 RESTful 设计规范，支持 JSON 格式的数据交互。

✨ 特性

🌍 全中文文档 - 清晰易懂的接口说明

🚀 完整示例 - 每个接口都包含请求代码示例

🔐 安全认证 - 支持多种身份验证方式

📦 丰富功能 - 覆盖文件管理、分享、支付等完整功能

🎯 标准响应 - 统一的响应结构，便于集成

🏗️ 架构概览

Cloudreve 提供了功能完善的云存储解决方案，支持：

多种存储策略 - 本地、七牛、阿里云 OSS、腾讯云 COS、又拍云、OneDrive、S3 兼容协议

离线下载 - Aria2 离线下载，支持磁力链接、BT 种子

在线预览 - 图片、音频、视频、Office 文档在线预览

WebDAV 协议 - 支持通过 WebDAV 协议访问

文件分享 - 创建公开/私密分享链接，支持密码保护和过期时间

🚀 快速开始

基础信息

API 基础 URL

https://your-cloudreve-domain.com

内容类型

Content-Type: application/json

响应格式
所有 API 响应都遵循统一的结构：

{
  "code": 0,           // 状态码，0 表示成功
  "msg": "",           // 消息提示
  "data": {}           // 响应数据
}

认证方式

Cloudreve API 支持以下认证方式：

1️⃣ Bearer Token 认证（推荐）

3️⃣ 无需认证

部分公开接口（如获取站点信息、验证码等）无需认证。

获取 Access Token

📚 主要功能模块

🌐 站点信息

获取实例版本、站点设置、验证码等基础信息。

GET /site/ping - 健康检查

GET /site/captcha - 获取验证码

GET /site/config - 获取站点设置

👤 用户管理

用户注册、登录、个人资料管理、存储容量查询。

POST /user/session - 用户登录

POST /user - 用户注册

GET /user/me - 获取当前用户信息

PATCH /user/me/avatar - 更新头像

GET /user/storage - 获取存储容量

🔐 会话管理

支持密码登录、双因素认证、OpenID 登录、Passkey 登录。

POST /user/session - 密码登录

POST /user/session/2fa - 双因素认证

POST /user/authn - Passkey 登录

DELETE /user/session - 退出登录

PUT /user/session - 刷新令牌

📁 文件管理

文件上传、下载、重命名、移动、删除、搜索、版本管理。

GET /directory{path} - 列出文件

PUT /directory{path} - 创建文件夹

GET /file/get/{id} - 获取文件信息

PUT /file/upload - 创建上传会话

POST /file/upload/{sessionId} - 上传分片

PATCH /object - 重命名/移动文件

DELETE /object - 删除文件

🔗 分享管理

创建、编辑、删除分享链接，支持密码保护和权限控制。

POST /share - 创建分享链接

GET /share/info/{id} - 获取分享信息

PATCH /share/{id} - 更新分享设置

DELETE /share/{id} - 删除分享链接

⬇️ 离线下载

创建远程下载任务，支持 HTTP、磁力链接、BT 种子。

POST /aria2/task - 创建下载任务

GET /aria2/task - 列出下载任务

GET /aria2/task/{id} - 获取任务进度

DELETE /aria2/task/{id} - 取消任务

💰 增值服务

支付、礼品码兑换、容量包购买。

POST /vas/pack - 创建支付

GET /vas/pack/{id} - 查询支付状态

POST /redeem - 兑换礼品码

🔌 WebDAV

WebDAV 账号管理，支持第三方客户端访问。

GET /webdav/accounts - 列出 WebDAV 账号

POST /webdav/accounts - 创建账号

DELETE /webdav/accounts/{id} - 删除账号

🔍 接口分类导航

🌐 站点信息

健康检查

获取验证码

获取站点设置

举报滥用

🔐 会话管理

令牌管理

OpenID 登录

通行密钥登录

准备登录

👤 用户管理

通行密钥管理

设置管理

用户注册

重置密码

获取头像

获取用户信息

存储容量查询

📁 文件管理

权限管理

上传管理

固定项管理

版本管理

直链管理

列出文件

文件操作（重命名/移动/删除）

缩略图获取

元数据更新

🔗 分享管理

创建分享

编辑分享

查询分享

删除分享

⚙️ 工作流

远程下载

压缩包管理

存储策略迁移

外部文件导入

💰 增值服务

支付管理

礼品码管理

👥 用户组

列出用户组

🔌 WebDAV

账号管理

📝 响应状态码

成功状态码

状态码	说明
0	请求成功

错误状态码

状态码	说明
40001	未提供认证信息
40003	认证信息无效
40011	用户不存在
40012	用户名或密码错误
40013	需要双因素认证
40021	文件不存在
40022	权限不足
40028	文件被锁定
50000	服务器内部错误

🛠️ 代码示例

JavaScript / Node.js

Python

cURL

💡 最佳实践

1. Token 管理

使用 refresh_token 自动刷新 access_token

安全存储 token，避免泄露

Token 过期时自动重新登录

2. 错误处理

3. 分片上传

对于大文件，使用分片上传：

4. 速率限制

建议每秒请求不超过 10 次

批量操作使用分页加载

合理使用缓存减少请求

🔗 相关链接

📘 官方网站

📖 英文 API 文档

💬 GitHub 仓库

🐛 问题反馈

💬 社区讨论

📦 Docker 镜像

📄 许可证

本 API 文档基于 GPL-3.0 许可证开源。

🤝 贡献

如果您发现文档中的错误或有改进建议，欢迎：

提交 Issue 报告问题

提交 Pull Request 改进文档

在社区中分享使用经验

✨ 感谢使用 Cloudreve API ✨

Built with ❤️ by Cloudreve Community

README

Cloudreve API 文档#

📖 文档说明#

✨ 特性#

🏗️ 架构概览#

🚀 快速开始#

基础信息#

认证方式#

1️⃣ Bearer Token 认证（推荐）#

2️⃣ Session Cookie 认证#

3️⃣ 无需认证#

获取 Access Token#

📚 主要功能模块#

🌐 站点信息#

👤 用户管理#

🔐 会话管理#

📁 文件管理#

🔗 分享管理#

⬇️ 离线下载#

💰 增值服务#

🔌 WebDAV#

🔍 接口分类导航#

🌐 站点信息#

🔐 会话管理#

👤 用户管理#

📁 文件管理#

🔗 分享管理#

⚙️ 工作流#

💰 增值服务#

👥 用户组#

🔌 WebDAV#

📝 响应状态码#

成功状态码#

错误状态码#

🛠️ 代码示例#

JavaScript / Node.js#

Python#

cURL#

💡 最佳实践#

1. Token 管理#

2. 错误处理#

3. 分片上传#

4. 速率限制#

🔗 相关链接#

📄 许可证#

🤝 贡献#

Cloudreve API 文档

📖 文档说明

✨ 特性

🏗️ 架构概览

🚀 快速开始

基础信息

认证方式

1️⃣ Bearer Token 认证（推荐）

2️⃣ Session Cookie 认证

3️⃣ 无需认证

获取 Access Token

📚 主要功能模块

🌐 站点信息

👤 用户管理

🔐 会话管理

📁 文件管理

🔗 分享管理

⬇️ 离线下载

💰 增值服务

🔌 WebDAV

🔍 接口分类导航

🌐 站点信息

🔐 会话管理

👤 用户管理

📁 文件管理

🔗 分享管理

⚙️ 工作流

💰 增值服务

👥 用户组

🔌 WebDAV

📝 响应状态码

成功状态码

错误状态码

🛠️ 代码示例

JavaScript / Node.js

Python

cURL

💡 最佳实践

1. Token 管理

2. 错误处理

3. 分片上传

4. 速率限制

🔗 相关链接

📄 许可证

🤝 贡献