使用 multipart/form-data 上传单个文件，最大 50 MB。上传后进入安全审核，available 状态才可挂载或作为消息内容。
前提
已完成 Endpoint 与鉴权配置，详见API 总览与认证。
配额与限制
- 单个工作空间下文件总容量上限为 100 GB。
- 文件保存时效为 30 天，超过 30 天的文件不保证可用，可能被自动清理。需要长期保留请定期重新上传。
- 通过该接口直传的单个文件最大 50 MB。
接口
POST /files
使用 multipart/form-data 编码。filename 自动从表单部分获取，mime_type 由服务端检测。
请求示例
响应示例
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 文件 ID，格式 file_<24位字母数字>（如 file_maznwes8t9rsysg5r5enkvpr） |
type | string | 固定为 file |
filename | string | 文件名（自上传时表单部分解析得到） |
mime_type | string | 服务端检测的 MIME 类型 |
size_bytes | int | 文件大小，单位字节 |
downloadable | bool | 是否支持下载。当前接口直传与会话沙箱拷贝均为 false |
status | string | 安全审核状态：available（通过，可挂载） / checking（审核中） / rejected（内容未通过） / type_rejected（类型不支持）。新上传文件默认 checking |
created_at | string | 上传时间，ISO 8601 |
requestId | string | 本次请求的唯一标识。Python SDK 中对应属性为 request_id |
作用域
普通上传返回的文件无 scope 字段（默认工作空间共享）；当文件被挂载到会话沙箱时，服务端会做内部拷贝并生成新的 file_id，该副本的元数据中带 scope: {"type": "session", "id": "sesn_..."}，仅对应会话可见。