开放 API 文档

通过个人中心生成的 API Token 鉴权调用，可上传、管理你自己的文件，并设置外链权限。

鉴权

每次请求携带 token 参数（GET 或 POST 均可）。服务端按 token 找到对应用户，所有操作仅限本人文件。

参数	说明
token	你的 API Token，32 位小写字符
act	操作类型：upload / list / setperm / rename / delete

权限位（perm）

文件外链权限用位掩码表示，多个权限相加。默认 0 表示完全私密（不生成任何外链）。

值	含义
1	分享页可访问（file.php 分享页）
2	直读外链（view.php 在线预览/直链）
4	允许下载（down.php）

例如 perm=6（2+4）= 允许直读和下载，但不开分享页；perm=7 = 全部开放。也可用 p_page/p_view/p_down 三个开关（值 1 生效）替代 perm。

1. 上传文件 act=upload

POST multipart/form-data

参数	必填	说明
file	是	文件字段（表单文件）
perm	否	上传后设置的权限位，默认 0（私密）
folder_id	否	目标文件夹 ID（须为本人文件夹，否则落到根目录）

相同 hash 的文件会秒传去重。返回字段见下方「文件对象」。若本人已传过同一文件，返回 exists=1。

curl -F "token=你的TOKEN" \
     -F "act=upload" \
     -F "perm=6" \
     -F "file=@/path/to/photo.jpg" \
     https://pan.zhangjiacheng.top/api.php

2. 我的文件列表 act=list

GET

参数	必填	说明
page	否	页码，默认 1
pagesize	否	每页数量 1-100，默认 20
kw	否	按文件名模糊搜索
folder_id	否	只看某文件夹（0=根目录，不传=全部）

curl "https://pan.zhangjiacheng.top/api.php?token=你的TOKEN&act=list&page=1&pagesize=20"

返回：{code:0, total, page, pagesize, list:[文件对象...]}

3. 设置权限 act=setperm

POST

参数	必填	说明
hash	是	文件 hash（32 位）
perm	二选一	权限位 0-7
p_page / p_view / p_down	二选一	三个开关（1 生效），未提供 perm 时使用

curl -d "token=你的TOKEN&act=setperm&hash=文件HASH&perm=6" \
     https://pan.zhangjiacheng.top/api.php

perm=0 会删除该文件的分享记录，变为完全私密。

4. 重命名 act=rename

POST

参数	必填	说明
hash	是	文件 hash
name	是	新文件名（自动补回原扩展名，最长 200 字）

curl -d "token=你的TOKEN&act=rename&hash=文件HASH&name=新名字" \
     https://pan.zhangjiacheng.top/api.php

5. 删除文件 act=delete

POST

参数	必填	说明
hash	是	文件 hash

curl -d "token=你的TOKEN&act=delete&hash=文件HASH" \
     https://pan.zhangjiacheng.top/api.php

会一并清理分享记录；仅当该 hash 无其它记录引用时才删除云端对象与缩略图（防误删被去重复用的文件）。被冻结的文件无法删除。

文件对象字段

字段	说明
id	文件 ID
name	文件名
hash	文件 hash（用于其它接口定位）
type	扩展名
size	大小（字节）
addtime	上传时间
downurl	下载直链（down.php）
viewurl	预览直链（view.php，仅可预览类型有）
thumburl	缩略图地址（图片/视频有；云存储返回云端直链）
perm	当前权限位
p_page / p_view / p_down	三档权限的 0/1 状态

外链是否真正可访问，取决于 perm 权限位。perm=0 时 downurl/viewurl 会被门禁拦截（403）。

错误码

code	说明
0	成功
-1	参数错误 / 操作失败（见 msg）
-2	token 无效或账号被封禁
-4	未知的 act