POST https://ark.cn-beijing.volces.com/api/v3/files
上传文件到方舟平台，供后续模型调用作为输入（如图像、视频、文档等）。文件在一定时间后过期删除。
鉴权#
本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数#
Body 参数#
file object 必选 | 上传的文件
需要上传的文件，要求为二进制文件。具体限制请参见 Files API 教程
purpose string 必选 | 文件用途
文件用途。
user_data：可以灵活使用的文件，能够用于任意用途。agent：智能体（Agent）场景使用的文件。
url string | 文件 URL
文件 URL，支持以下两种 URL 类型：
-
HTTP/HTTPS URL：公网可直接访问的文件 URL，请确保文件 URL 可被访问。
-
TOS URI：对象存储 TOS 专属的资源定位标识，格式为
tos://<bucket>/<prefix>/<file_name>。其中，<bucket>、<prefix>和<file_name>分别表示存储桶名称、存储路径和文件名。详细使用说明可参考 TOS URI 上传方式 部分，也可前往 火山引擎对象存储 TOS Bucket 中管理存储桶。
tos object | TOS 存储配置
文件存储的 TOS 信息。TOS 即火山引擎对象存储服务；配置本参数后，上传文件将存储至用户指定的火山引擎对象存储 TOS Bucket 中，不再存入方舟平台默认托管存储空间。
bucket string | 存储桶名称
tos.bucket
目标文件待写入的 TOS 存储桶名称，该存储桶需提前完成创建，参考 创建存储桶。
prefix string | 存储路径前缀
tos.prefix
文件在目标 TOS 存储桶内的存放前缀路径，入参填写相对路径格式，上传后文件将落地至该前缀目录下。示例：arkfiles/。
preprocess_configs object | 预处理配置
用于设置不同文件类型的预处理规则。
video object | 视频预处理配置
preprocess_configs.video
视频预处理相关配置。
fps number 默认值 1 | 抽帧帧率
preprocess_configs.video.fps
每秒钟从视频中抽取指定数量的图像。取值越高，对于视频中画面变化理解越精细；取值越低，对于视频中画面变化感知减弱，但是使用的 token 花费少，速度也更快。
取值范围：[0.2, 5]
model string | 预处理模型
preprocess_configs.video.model
使用该文件进行推理时，要使用的视频理解模型 ID（Model ID）或 Endpoint ID。
max_video_tokens integer | 视频最大 tokens 数
preprocess_configs.video.max_video_tokens
视频最大 tokens 数，值越大保留的视频信息越多。
取值范围：[10240, 204800]
min_frame_tokens integer | 单帧最小 tokens 数
preprocess_configs.video.min_frame_tokens
单帧最小 tokens 数，用于控制单帧压缩的下限。值越小，允许对单帧进行更大的压缩，但单帧细节下降。
取值范围：[16, 128]
max_frame_tokens integer | 单帧最大 tokens 数
preprocess_configs.video.max_frame_tokens
单帧最大 tokens 数，用于控制单帧质量的上限。值越大，允许对单帧保留更多的细节。
取值范围：[128, 640]
min_frames integer | 最小抽帧数
preprocess_configs.video.min_frames
最小抽帧数，用于保证短视频具备足够的处理帧数。若 fps 字段抽帧总数小于 min_frames，则优先按照 min_frames 配置要求抽帧。
取值范围：[5, 16]
expire_at integer | 文件过期时间
设置存储的有效期，需要传入 UTC Unix 时间戳（单位：秒）。最少保留 1 天，最多保留 30 天；不传时默认保留 7 天（当前时刻 + 604800）
响应参数#
object string | 对象类型
对象类型，固定为 file。
id string | 文件 ID
文件的唯一标识符。
purpose string | 文件用途
文件用途。
user_data：可以灵活使用的文件，能够用于任意用途。agent：智能体（Agent）场景使用的文件。
scope object | 文件所属作用域信息
文件所属作用域信息，用于标识该文件创建时归属的会话上下文。
type string | 作用域类型
scope.type
作用域类型，当前固定取值为 session。
id string | 作用域 ID
scope.id
作用域 ID，返回对应的会话 ID。
filename string | 文件名
tos object | 文件存储的 TOS 信息
文件存储的 TOS 信息。TOS 即火山引擎对象存储服务，仅当用户传入 tos 参数时才会返回。
bucket string | 目标文件待写入的 TOS 存储桶名称
tos.bucket
object_key string | 文件存储在 TOS 中的路径信息
tos.object_key
bytes integer | 文件大小
文件大小，以 bytes 为单位。
created_at integer | 创建时间
本次请求上传文件时的 Unix 时间戳（秒）。
expire_at integer | 过期时间
文件过期时间的 Unix 时间戳（秒）。
mime_type string | MIME 类型
文件的 MIME 类型，如 application/pdf。
status string | 文件处理状态
文件处理状态。
processing：文件正在预处理，无法使用。active：文件已处理完成，可以使用。failed：文件上传失败，错误详情查看error字段。
error object | 错误信息
文件上传失败时返回的错误对象，即 status 取值为 failed 时才会返回该字段。
code string | 错误码
error.code
message string | 错误描述信息
error.message
preprocess_configs object | 预处理配置
用于设置不同文件类型的预处理规则。
video object | 视频预处理配置
preprocess_configs.video
视频预处理相关配置。
fps number | 抽帧帧率
preprocess_configs.video.fps
每秒钟从视频中抽取指定数量的图像。取值越高，对于视频中画面变化理解越精细；取值越低，对于视频中画面变化感知减弱，但是使用的 token 花费少，速度也更快。
取值范围：[0.2, 5]
model string | 预处理模型
preprocess_configs.video.model
使用该文件进行推理时，要使用的视频理解模型 ID（Model ID）或 Endpoint ID。
max_video_tokens integer | 视频最大 tokens 数
preprocess_configs.video.max_video_tokens
视频最大 tokens 数，值越大保留的视频信息越多。
取值范围：[10240, 204800]
min_frame_tokens integer | 单帧最小 tokens 数
preprocess_configs.video.min_frame_tokens
单帧最小 tokens 数，用于控制单帧压缩的下限。值越小，允许对单帧进行更大的压缩，但单帧细节下降。
取值范围：[16, 128]
max_frame_tokens integer | 单帧最大 tokens 数
preprocess_configs.video.max_frame_tokens
单帧最大 tokens 数，用于控制单帧质量的上限。值越大，允许对单帧保留更多的细节。
取值范围：[128, 640]
min_frames integer | 最小抽帧数
preprocess_configs.video.min_frames
最小抽帧数，用于保证短视频具备足够的处理帧数。若 fps 字段抽帧总数小于 min_frames，则优先按照 min_frames 配置要求抽帧。
取值范围：[5, 16]