火山方舟
火山方舟
API参考
请输入
- 文档首页
火山方舟Files API查询文件详情
复制全文
下载 pdf查询文件详情
文档反馈
问问助手GET https://ark.cn-beijing.volces.com/api/v3/files/{file_id}
通过文件 ID 查询指定文件的详细信息。
鉴权
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数
Path 参数
file_id string 必选 | 文件 ID
要查询的文件 ID
响应参数
created_at integer | 创建时间
文件上传时的 Unix 时间戳（秒）
expire_at integer | 过期时间
文件过期时间的 Unix 时间戳（秒）。文件过期后将无法访问，需重新上传
filename string | 原始文件名
上传时的原始文件名
id string | 文件 ID
文件的唯一标识符
object string | 对象类型
对象类型，固定为 file
purpose string | 文件用途
文件用途。
- user_data：可以灵活使用的文件，能够用于任意用途。
- agent：智能体（Agent）场景使用的文件。
status string | 文件状态
文件处理状态。常见取值为 active（处理完成，可用于推理）、processing（处理中）、failed（处理失败）
bytes integer | 文件大小
文件大小，单位为字节（Bytes）
注意
仅在文件处理状态 status 为 active 时返回。
download_url string | 下载 URL
服务端签发的临时预签名下载地址，可用于下载文件内容。
注意
该地址包含临时访问凭证。请仅向已授权用户提供，并避免写入日志、长期缓存或公开分享。
error object | 错误信息
文件上传或处理失败时返回的错误信息对象，包含错误码、错误消息等字段
注意
仅在文件处理状态 status 为 failed 时返回。
code string | 错误码
error.code
message string | 错误描述信息
error.message
mime_type string | MIME 类型
文件的 MIME 类型，例如 video/mp4、image/jpeg
preprocess_configs object | 预处理配置
上传文件时设置的预处理规则配置，按文件类型分组（如视频抽帧规则）
video object | 视频预处理配置
preprocess_configs.video
视频文件的预处理配置
fps number | 抽帧帧率
preprocess_configs.video.fps
视频抽帧的帧率（Frames Per Second），用于设置视频预处理时每秒采样的画面帧数
model string | 预处理模型
preprocess_configs.video.model
视频预处理使用的模型标识符（可选）
scope object | 文件所属作用域信息
文件所属作用域信息，用于标识该文件创建时归属的会话上下文。
id string | 作用域 ID
scope.id
作用域 ID，返回对应的会话 ID。
type string | 作用域类型
scope.type
作用域类型，当前固定取值为 session。
默认
发起调试等同于请求真实调用，可能产生云产品费用，请谨慎操作！
Request
cURL
curl https://ark.cn-beijing.volces.com/api/v3/files/file-20251119**** \
-H "Authorization: Bearer $ARK_API_KEY"Response
{
"object": "file",
"id": "file-20251119****",
"purpose": "user_data",
"filename": "demo.mp4",
"bytes": 18773126,
"mime_type": "video/mp4",
"created_at": 1763552708,
"expire_at": 1764157507,
"status": "active"
}最近更新时间：2026.10.14 16:21:28
这个页面对您有帮助吗？
有用
有用
无用
无用