上传文件 - Qoder CN

上传文本类文件，供 Session、工具或 Agent 输出使用。 POST /api/v1/cloud/files 上传一个文本类文件，并返回 File 对象。

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT>`
`Content-Type`	是	`multipart/form-data`

请求体

字段	类型	必选	说明
`file`	file	是	文本类文件内容。支持类型见支持上传的文件类型
`name`	string	否	存储文件名。不传时使用上传文件名。服务端清理后长度必须为 1-255 byte，且不能是 `.` 或 `..`
`metadata`	JSON string	否	作为表单字段传入的合法 JSON。原始长度最大 8 KB，省略时为 `{}`

示例请求

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/files" \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./my-document.txt" \
  -F "name=my-document.txt" \
  -F 'metadata={"project":"demo"}'

示例响应

HTTP 200 OK

{
  "id": "file_019e3bb8c1387743bf4ef115aae5acb1",
  "type": "file",
  "filename": "my-document.txt",
  "mime_type": "text/plain",
  "size_bytes": 110,
  "downloadable": false,
  "scope": null,
  "metadata": {
    "project": "demo"
  },
  "created_at": "2026-05-18T15:33:44Z"
}

响应字段

字段	类型	说明
`id`	string	File ID，前缀为 `file_`
`type`	string	固定为 `"file"`
`filename`	string	存储后的文件名
`size_bytes`	integer	文件大小，单位 byte
`mime_type`	string	上传时提供或根据文件名检测出的 MIME type
`downloadable`	boolean	是否可通过 `/content` 端点下载
`scope`	object \| null	文件关联到其他资源时的 scope，例如 `{ "id": "sess_...", "type": "session" }`
`metadata`	object	上传时传入的自定义元数据对象；省略时为 `{}`
`created_at`	string	UTC 创建时间，RFC 3339 格式

注意事项

multipart 请求体限制约为 5 MB 文件内容加上表单开销。
只接受文本类文件。二进制文档、图片、音视频和压缩包会被拒绝。
服务端会对 name 取基础文件名，并将路径分隔符或空字节替换为 _。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	缺少 `file`、multipart 表单非法、文件类型不支持、`name` 非法、`metadata` 非法或请求体过大
401	`authentication_error`	缺少或无效的认证令牌
500	`api_error`	文件存储后端不可用

完整错误信封说明详见错误参考。

​请求头

​请求体

​示例请求

​示例响应

​响应字段

​注意事项

​错误码

请求头

请求体

示例请求

示例响应

响应字段

注意事项

错误码