GET https://ark.cn-beijing.volces.com/api/v3/files
获取当前账号下已上传的文件列表，支持按用途筛选与基于游标的分页查询。
鉴权#
本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数#
Query 参数#
在 URL Query String 中传入。
after string | 分页游标
游标参数，返回该文件 ID 之后的文件，用于分页拉取下一页数据。通常传入上一页响应中的 last_id
limit integer 默认值 100 | 单次返回数量
控制单次返回的最大文件数。
order string 默认值 desc | 排序方式
按照文件 created_at 的时间戳顺序，控制文件的排序方式：
asc：正序排列；desc：倒序排列。
purpose string | 文件用途筛选
按文件用途进行筛选，仅返回具有指定用途的文件。
user_data：可以灵活使用的文件，能够用于任意用途。agent：智能体（Agent）场景使用的文件。
scope_id string | 作用域 ID（Session 维度）
当前仅支持传入 Session ID，用于筛选该 Session 在 /mnt/session/outputs/ 目录中生成的产物。
响应参数#
data object[] | 文件列表
文件对象列表，元素结构与 查询文件详情 接口返回的单个文件对象一致
created_at integer | 创建时间
data.created_at
文件上传时的 Unix 时间戳（秒）
expire_at integer | 过期时间
data.expire_at
文件过期时间的 Unix 时间戳（秒）。文件过期后将无法访问，需重新上传
filename string | 原始文件名
data.filename
上传时的原始文件名
id string | 文件 ID
data.id
文件的唯一标识符
object string | 对象类型
data.object
对象类型，固定为 file
purpose string | 文件用途
data.purpose
文件用途。
user_data：可以灵活使用的文件，能够用于任意用途。agent：智能体（Agent）场景使用的文件。
status string | 文件状态
data.status
文件处理状态。常见取值为 active（处理完成，可用于推理）、processing（处理中）、failed（处理失败）
bytes integer | 文件大小
data.bytes
文件大小，单位为字节（Bytes）
download_url string | 下载 URL
data.download_url
服务端签发的临时预签名下载地址，可用于下载文件内容。
error object | 错误信息
data.error
文件上传或处理失败时返回的错误信息对象，包含错误码、错误消息等字段
code string | 错误码
data.error.code
机器可读的错误码
message string | 错误消息
data.error.message
人类可读的错误描述信息
param string | 错误参数
data.error.param
触发该错误的请求参数名（如有）
type string | 错误类型
data.error.type
错误类型标识
mime_type string | MIME 类型
data.mime_type
文件的 MIME 类型，例如 video/mp4、image/jpeg
preprocess_configs object | 预处理配置
data.preprocess_configs
上传文件时设置的预处理规则配置，按文件类型分组（如视频抽帧规则）
video object | 视频预处理配置
data.preprocess_configs.video
视频文件的预处理配置
fps number | 抽帧帧率
data.preprocess_configs.video.fps
视频抽帧的帧率（Frames Per Second），用于设置视频预处理时每秒采样的画面帧数
model string | 预处理模型
data.preprocess_configs.video.model
视频预处理使用的模型标识符（可选）
scope object | 文件所属作用域信息
data.scope
文件所属作用域信息，用于标识该文件创建时归属的会话上下文。
id string | 作用域 ID
data.scope.id
作用域 ID，返回对应的会话 ID。
type string | 作用域类型
data.scope.type
作用域类型，当前固定取值为 session。
first_id string | 首条文件 ID
当前响应中第一条文件数据的 ID
has_more boolean | 是否有更多数据
标识是否还有更多数据未返回：
true：存在未返回的数据，可继续使用last_id作为after拉取下一页；false：已返回全部数据
last_id string | 末条文件 ID
当前响应中最后一条文件数据的 ID，可用作下一页请求的 after 参数
object string | 对象类型
对象类型，固定为 list