*file object 必选 | 上传的文件 *需要上传的文件，要求为二进制文件。具体限制请参见 Files API 教程 *注意 *文件上传支持二进制文件和文件 URL 两种传入方式，file、url 为二选一必填参数，不可同时传参。

*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 中管理存储桶。 *注意 *文件上传支持二进制文件和文件 URL 两种传入方式，file、url 为二选一必填参数，不可同时传参。 *传入 TOS URI 时，必须将文件存储到火山引擎对象存储 TOS Bucket 中，此时 tos.bucket、tos.prefix 为必填参数。

*tos object | TOS 存储配置 *文件存储的 TOS 信息。TOS 即火山引擎对象存储服务；配置本参数后，上传文件将存储至用户指定的火山引擎对象存储 TOS Bucket 中，不再存入方舟平台默认托管存储空间。 *说明 *不传 tos 参数：文件存储在方舟平台托管的默认存储空间，单文件不超过 512 MB。已存入方舟平台托管存储的历史文件，不会自动迁移至其他存储位置。 *传 tos 参数：文件存储在用户指定的火山引擎对象存储 TOS Bucket 中，视频文件不超过 2 GB，其他类型文件不超过 512 MB，支持格式详见 文件类型。授权写入用户指定 TOS Bucket 中的文件，不支持在 TOS 侧删除或修改；如需删除文件，可调用 Files API 删除，参考 删除文件。 *bucket string | 存储桶名称 *tos.bucket *目标文件待写入的 TOS 存储桶名称，该存储桶需提前完成创建，参考 创建存储桶。 *prefix string | 存储路径前缀 *tos.prefix *文件在目标 TOS 存储桶内的存放前缀路径，入参填写相对路径格式，上传后文件将落地至该前缀目录下。示例：arkfiles/。

*preprocess_configs object | 预处理配置 *用于设置不同文件类型的预处理规则。 *video object | 视频预处理配置 *preprocess_configs.video *视频预处理相关配置。 *说明 *配置 model 字段后，系统将根据对应模型的抽帧策略，自动填充 max_video_tokens、min_frame_tokens、max_frame_tokens、min_frames 四个字段的默认值，具体取值参考 模型抽帧策略说明。 *fps number 默认值 1 | 抽帧帧率 *preprocess_configs.video.fps *每秒钟从视频中抽取指定数量的图像。取值越高，对于视频中画面变化理解越精细；取值越低，对于视频中画面变化感知减弱，但是使用的 token 花费少，速度也更快。 *注意 *取值范围：[0.2, 5]。单视频 token 用量范围在 [10k, 80k]。 *取值范围：[0.2, 5] *model string | 预处理模型 *preprocess_configs.video.model *使用该文件进行推理时，要使用的视频理解模型 ID（Model ID）或 Endpoint ID。 *说明 *Files API 中设置的模型 ID 与推理使用的模型 ID 不强耦合，只影响上传视频文件时预处理抽帧策略。关于预处理抽帧策略，参见 抽帧策略。 *传入模型 ID：传入不同的模型 ID 会采用不同的抽帧策略。 *传入 Endpoint ID：会按照上传时 Endpoint ID 映射的模型对应的抽帧策略进行抽帧。 *不传该参数时：默认采用 doubao-seed-1.8 之前的模型对应的抽帧策略。 *注意 *如需处理视频中的音频内容，该字段需指定为支持音频理解的模型，具体支持的模型可参见 模型列表。 *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） *注意 *取值范围：[当前时刻+86400, 当前时刻+2592000]，即最少保留 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]。单视频 token 用量范围在 [10k, 80k]。 *取值范围：[0.2, 5] *model string | 预处理模型 *preprocess_configs.video.model *使用该文件进行推理时，要使用的视频理解模型 ID（Model ID）或 Endpoint ID。 *说明 *Files API 中设置的模型 ID 与推理使用的模型 ID 不强耦合，只影响上传视频文件时预处理抽帧策略。关于预处理抽帧策略，参见 抽帧策略。 *传入模型 ID：传入不同的模型 ID 会采用不同的抽帧策略。 *传入 Endpoint ID：会按照上传时 Endpoint ID 映射的模型对应的抽帧策略进行抽帧。 *不传该参数时：默认采用 doubao-seed-1.8 之前的模型对应的抽帧策略。 *注意 *如需处理视频中的音频内容，该字段需指定为支持音频理解的模型，具体支持的模型可参见 模型列表。 *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]