> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 上传文件

> 上传文本类文件，供 Session、工具或 Agent 输出使用。

`POST /api/v1/cloud/files`

上传一个文本类文件，并返回 [File 对象](/zh/cloud-agents/api/files/schemas#file-对象)。

## 请求头

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

## 请求体

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

## 示例请求

```bash theme={null}
curl -X POST "https://api.qoder.com/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**

```json theme={null}
{
  "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`             | 文件存储后端不可用                                                      |

完整错误信封说明详见 [错误参考](/zh/cloud-agents/api/conventions/errors)。

## 相关

<CardGroup cols={2}>
  <Card title="附加与下载文件" icon="paperclip" href="/zh/cloud-agents/files">
    上传文件为 Agent 提供上下文，并下载 Agent 产出的文件。
  </Card>
</CardGroup>