# 创建前上传本地文件

在创建知识库前上传本地文件。上传成功只返回待绑定的文件 ID；必须在[创建知识库并添加数据源](create-knowledge-base-with-sources.md)时作为 `local_file` 来源绑定。

```text
POST https://moi.matrixorigin.cn/newmoi/semantic-models/local-files/upload
```

## 调用前准备

准备有目标工作区创建知识库权限的个人访问令牌和工作区 ID。请求使用 `multipart/form-data`，表单字段名固定为 `file`。

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/semantic-models/local-files/upload" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F "file=@./product-guide.pdf"
```

## 成功响应

字段路径中的 `[]` 表示数组中的每一项。例如，`sources[]` 表示 `sources` 数组中的每一项。

成功时返回 `200`。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": { "file_id": "file_01" }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.file_id` | string | 待绑定文件 ID。创建知识库时与文件名一起传入 `sources[]`。 |

## 常见错误

| HTTP 状态码 | 错误代码 | 常见原因 | 建议操作 |
| --- | --- | --- | --- |
| `400` | `ErrParamInvalid` | 未提交 `file` 或文件名为空。 | 使用 `-F "file=@路径"` 提交文件。 |
| `401` | `ErrUnauthorized` | API Key 无效或已失效。 | 检查 API Key。 |
| `403` | `ErrForbidden` | 没有工作区创建权限。 | 检查工作区授权。 |

## 后续操作

调用[创建知识库并添加数据源](create-knowledge-base-with-sources.md)，将 `data.file_id` 和原文件名作为 `local_file` 来源提交。