MeBox/115doc/115开放平台/API列表/文件管理/获取文件列表.md

获取文件列表

基本信息

属性	内容
接口名称	获取文件列表
接口版本	v1.0
接口路径	/files
请求方法	GET
接口状态	生产环境

接口说明

获取指定目录中的文件和文件夹列表，支持分页、排序以及按文件类型、后缀名和星标状态筛选。

接口地址

https://proapi.115.com/open/ufile/files

请求方式

GET

认证方式

Authorization: Bearer access_token

请求参数

参数名	类型	必填	默认值	说明	约束/示例
cid	string	否	"0"	目录ID，对应 parent_id；根目录ID为 0	"0"
type	int	否	0	文件类型，见下方枚举表格	1
limit	int	否	20	查询数量，最大1150	20
offset	int	否	0	查询起始位置	0
suffix	string	否	""	文件后缀名	"pdf"
asc	int	否	0	排序方向：1-升序，0-降序	0
o	string	否	user_ptime	排序字段，见下方枚举表格	file_name
custom_order	int	否	0	排序模式，见下方枚举表格	0
stdir	int	否	0	筛选文件时是否显示文件夹：1-显示，0-不显示	1
star	int	否	0	星标筛选：1-仅显示星标文件，0-全部	0
cur	int	否	0	是否只显示当前文件夹内的文件：1-是，0-否	1
show_dir	int	否	0	是否显示目录：1-是，0-否	0

请求参数中的 type 字段枚举

值	说明	备注
1	文档	-
2	图片	-
3	音频	-
4	视频	-
5	压缩包	-
6	应用	-
7	书籍	-

请求参数中的 o 字段枚举

值	说明	备注
file_name	文件名	-
file_size	文件大小	-
user_ptime	上传时间	默认值
user_utime	更新时间	-
file_type	文件类型	-

请求参数中的 custom_order 字段枚举

值	说明	备注
0	使用记忆排序，自定义排序失效	默认值
1	使用自定义排序，不使用记忆排序	-
2	使用自定义排序，非文件夹置顶	-

请求示例

curl -G 'https://proapi.115.com/open/ufile/files' \
  -H 'Authorization: Bearer access_token' \
  --data-urlencode 'cid=0' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'offset=0'

响应字段说明

字段	类型	描述
data	object[]	文件和文件夹列表
data[].fid	string	文件或文件夹ID
data[].aid	string	文件状态：1-正常，7-已删除(回收站)，120-彻底删除
data[].pid	string	父目录ID
data[].fc	string	文件分类：0-文件夹，1-文件
data[].fn	string	文件或文件夹名称
data[].fco	string	文件夹封面
data[].ism	string	是否星标，1表示星标
data[].isp	int	是否加密，1表示加密
data[].pc	string	文件提取码
data[].upt	int	修改时间
data[].uet	int	修改时间
data[].uppt	int	上传时间
data[].cm	int	特殊目录标识
data[].fdesc	string	文件备注
data[].ispl	int	是否统计文件夹下视频时长
data[].fl	object[]	文件标签
data[].fl[].id	string	文件标签ID
data[].fl[].name	string	文件标签名称
data[].fl[].sort	string	文件标签排序
data[].fl[].color	string	文件标签颜色
data[].fl[].is_default	int	文件标签类型：0-最近使用，1-非最近使用，2-默认标签
data[].fl[].update_time	int	文件标签更新时间
data[].fl[].create_time	int	文件标签创建时间
data[].sha1	string	文件SHA-1值
data[].fs	int	文件大小，单位为字节
data[].fta	string	文件状态：0或2-未上传完成，1-已上传完成
data[].ico	string	文件后缀名
data[].fatr	string	音频长度
data[].isv	int	是否为视频
data[].def	int	视频清晰度：1-标清，2-高清，3-超清，4-1080P，5-4K，100-原画
data[].def2	int	视频清晰度：1-标清，2-高清，3-超清，4-1080P，5-4K，100-原画
data[].play_long	int	音视频时长，单位为秒
data[].v_img	string	视频缩略图地址
data[].thumb	string	图片缩略图地址
data[].uo	string	原图地址
count	int	当前目录文件数量
sys_count	int	系统文件夹数量
offset	int	偏移量
limit	int	分页数量
aid	string	文件状态：1-正常，7-已删除(回收站)，120-彻底删除
cid	int	父目录ID
is_asc	int	排序方向：1-升序，0-降序
min_size	int	最小文件大小筛选值
max_size	int	最大文件大小筛选值
sys_dir	string	系统目录
hide_data	string	是否返回文件数据
record_open_time	string	是否记录文件夹打开时间
star	int	是否星标：1-星标，0-未星标
type	int	一级筛选大分类，见请求参数中的 type 字段枚举
suffix	string	一级筛选选择“其他”时填写的后缀名
path	object[]	父目录树
path[].name	string	父目录名称
path[].aid	int	父目录文件状态
path[].cid	int	父目录ID
path[].pid	int	上级父目录ID
path[].isp	int	父目录是否加密
path[].p_cid	string	父目录路径标识
path[].fv	string	父目录属性
cur	int	是否只显示当前文件夹内的文件
stdir	int	筛选文件时是否显示文件夹
fields	string	指定返回字段
order	string	实际使用的排序字段
state	boolean	接口状态，true表示成功
code	int	异常码
message	string	异常信息

响应示例

{
  "data": [],
  "count": 0,
  "sys_count": 0,
  "offset": 0,
  "limit": 20,
  "aid": "1",
  "cid": 0,
  "is_asc": 0,
  "min_size": 0,
  "max_size": 0,
  "sys_dir": "",
  "hide_data": "",
  "record_open_time": "",
  "star": 0,
  "type": 0,
  "suffix": "",
  "path": [],
  "cur": 0,
  "stdir": 0,
  "fields": "",
  "order": "user_ptime",
  "state": true,
  "code": 0,
  "message": ""
}

注意事项

• limit 最大为1150。
• 当 cid 指向不存在或已删除的目录时，接口返回异常；当目录为加密目录时，不返回目录内容。
• user_id 由服务端根据 access token 获取，无需传入。

修改历史

修改时间	修改说明
2025年04月01日(周二) 00:00:00	创建文档