# 模型文件上传

ModelVerse 提供 OpenAI 兼容的文件上传接口。您可以先上传本地文件获取 `file_id`，再在支持文件输入的模型请求中引用该文件。

本文档仅介绍 `purpose` 为三段式模型标识（`xxx:xxx:modelname`）的文件上传方式。其他 `purpose` 类型请参考对应的功能文档。

## 使用限制

- `purpose` 必须包含三个以英文冒号（`:`）分隔的部分，第三部分必须是后续调用的模型名称。
- 例如，为 `deepseek-v4-flash-vision-exp` 上传文件时，`purpose` 填写 `deepseek:version:deepseek-v4-flash-vision-exp`。
- 单次上传请求最大为 1 GB，文件格式和大小还须符合目标模型的要求。
- 文件有效期为创建后的 24 小时，请在过期前使用返回的 `file_id`。
- 文件仅可由上传文件时所属公司和项目下的 API Key 使用。后续模型请求中的模型名称必须与 `purpose` 的第三部分一致。

## 上传文件

**请求**

- **方法 / 路径**：`POST /v1/files`
- **Content-Type**：`multipart/form-data`
- **请求头**：`Authorization: Bearer <your_api_key>`

**表单字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `purpose` | string | 是 | 三段式模型标识，格式为 `xxx:xxx:modelname` |
| `file` | binary | 是 | 要上传的本地文件 |

**请求示例**

```bash
curl -X POST "https://api.modelverse.cn/v1/files" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -F "purpose=deepseek:version:deepseek-v4-flash-vision-exp" \
  -F "file=@example.pdf"
```

**返回示例**

```json
{
  "id": "file-abc123",
  "object": "file",
  "bytes": 2456789,
  "created_at": 1787792400,
  "expires_at": 1787878800,
  "filename": "example.pdf",
  "purpose": "deepseek:version:deepseek-v4-flash-vision-exp",
  "status": "processed"
}
```

**返回字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 文件 ID，在后续模型请求中作为 `file_id` 使用 |
| `object` | string | 对象类型，固定为 `file` |
| `bytes` | int64 | 文件大小，单位为字节 |
| `created_at` | int64 | 文件创建时间，Unix 秒级时间戳 |
| `expires_at` | int64 | 文件过期时间，Unix 秒级时间戳 |
| `filename` | string | 文件名 |
| `purpose` | string | 请求中提交的三段式模型标识 |
| `status` | string | 文件状态；上传成功时为 `processed` |

上传成功后，将响应中的 `id` 作为后续模型请求的 `file_id`。上传和模型请求应使用同一项目下的 API Key。