# Files API

Files API 让你上传文件，之后通过 `file_id` 引用。可以上传两类文件：

- **图片**：JPEG、PNG、GIF、WebP，格式由文件实际内容判断。引用方式见 [图像理解](https://api-docs.deepseek.com/zh-cn/guides/vision.md)。
- **文档**：PDF、Word、PowerPoint、Excel、电子书与纯文本。引用方式见 [文件解析](https://api-docs.deepseek.com/zh-cn/guides/document_parsing.md)。

上传的文件与 `deepseek-flash` 模型配合使用。

***

## 上传文件

以 `multipart/form-data` 请求调用 `POST /files` 上传文件。单个文件的大小上限取决于文件类型：图片 **64 MiB**，PDF、Word、PowerPoint 等文档 **100 MiB**，纯文本、表格与电子书 **32 MiB**。上传时限同样取决于文件类型：PDF、Word、PowerPoint 等文档需在 **120 秒**内上传完成，其他文件需在 **10 分钟**内上传完成。

表单字段：

| 字段                       | 是否必填 | 说明                                                                            |
| ------------------------ | ---- | ----------------------------------------------------------------------------- |
| `file`                   | 是    | 要上传的文件。可上传的文件类型取决于 `purpose`，见下表。                                             |
| `purpose`                | 是    | 文件的用途。取值见下表。                                                                  |
| `expires_after[anchor]`  | 否    | 若提供，必须为 `created_at`。需与 `expires_after[seconds]` 一起使用。                        |
| `expires_after[seconds]` | 否    | 有效期（秒），取值在 `3600` 到 `2592000` 之间（1 小时到 30 天）。不传这两个 `expires_after` 字段则文件永久有效。 |

| `purpose`                 | 文件                                                                           | 用途                                                                                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_data`               | 图片（JPEG、PNG、GIF、WebP）；纯文本（txt、md、csv、json、代码文件等）；表格（XLSX、XLS）与电子书（EPUB、MOBI） | 在对话请求中引用图片，见 [图像理解](https://api-docs.deepseek.com/zh-cn/guides/vision.md)。纯文本、表格与电子书见 [文件解析](https://api-docs.deepseek.com/zh-cn/guides/document_parsing.md#text-files) |
| `text_recognition`        | PDF、Word（DOC、DOCX）、PowerPoint（PPT、PPTX），以及 PNG、JPEG、WebP、GIF、BMP、TIFF 等图片    | 只解析文字，文档里的图不交给模型，见 [文件解析](https://api-docs.deepseek.com/zh-cn/guides/document_parsing.md)                                                                               |
| `rich_layout_recognition` | 同上                                                                           | 图文混排解析：文字和文档里的图一起交给模型，见 [文件解析](https://api-docs.deepseek.com/zh-cn/guides/document_parsing.md)                                                                          |

上传文档时，`purpose` 须放在 `file` 字段之前。以 `user_data` 上传 PDF、Word、PowerPoint 文件会返回 `400`。

```python
from openai import OpenAI

client = OpenAI(api_key="<DeepSeek API Key>", base_url="https://api.deepseek.com")

with open("image.jpg", "rb") as f:
    uploaded = client.files.create(file=f, purpose="user_data")

print(uploaded.id)  # file-api-xxxxxxxxxxxxxxxx
```

```bash
curl https://api.deepseek.com/files \
  -H "Authorization: Bearer <DeepSeek API Key>" \
  -F purpose="user_data" \
  -F file="@image.jpg"
```

响应描述了已存储的文件：

```json
{
  "id": "file-api-xxxxxxxxxxxxxxxx",
  "object": "file",
  "bytes": 102400,
  "created_at": 1700000000,
  "filename": "image.jpg",
  "purpose": "user_data",
  "expires_at": 1700003600
}
```

只有在上传时设置了有效期，`expires_at` 才会出现。

***

## 列出文件

```python
files = client.files.list()
for f in files.data:
    print(f.id, f.filename)
```

```bash
curl https://api.deepseek.com/files \
  -H "Authorization: Bearer <DeepSeek API Key>"
```

查询参数：

| 参数        | 说明                                                                |
| --------- | ----------------------------------------------------------------- |
| `after`   | 用于分页的 `file_id` 游标；返回此文件之后的文件。                                    |
| `limit`   | 返回的文件数量，取值在 `1` 到 `1000` 之间。                                      |
| `order`   | 按创建时间排序：`asc`（默认）或 `desc`。                                        |
| `purpose` | 按用途过滤。`user_data`、`text_recognition` 或 `rich_layout_recognition`。 |

响应为分页列表：

```json
{
  "object": "list",
  "data": [
    {
      "id": "file-api-xxxxxxxxxxxxxxxx",
      "object": "file",
      "bytes": 102400,
      "created_at": 1700000000,
      "filename": "image.jpg",
      "purpose": "user_data"
    }
  ],
  "first_id": "file-api-xxxxxxxxxxxxxxxx",
  "last_id": "file-api-xxxxxxxxxxxxxxxx",
  "has_more": false
}
```

***

## 查询文件信息

```python
info = client.files.retrieve("file-api-xxxxxxxxxxxxxxxx")
print(info.filename, info.bytes)
```

```bash
curl https://api.deepseek.com/files/file-api-xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer <DeepSeek API Key>"
```

***

## 删除文件

```python
client.files.delete("file-api-xxxxxxxxxxxxxxxx")
```

```bash
curl -X DELETE https://api.deepseek.com/files/file-api-xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer <DeepSeek API Key>"
```

```json
{
  "id": "file-api-xxxxxxxxxxxxxxxx",
  "object": "file",
  "deleted": true
}
```

***

## 在对话请求中使用已上传的文件

使用 `file` 内容块引用返回的 `file_id`：

```python
response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "这张图片里有什么？"},
                {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
            ],
        },
    ],
)
print(response.choices[0].message.content)
```

文件归属于你的账号：同一账号下的所有 API key 共享文件，且可被任一 API 家族引用。注意：通过 Anthropic 兼容 `/messages` 端点引用文件时需携带 `anthropic-beta: files-api-2025-04-14` 请求头。

与内联（base64）图片不同，通过 `file_id` 引用的文件不受 32 MiB 单图限制，请求中单张最大 64 MiB。

`file` 块也可以通过 `file_data` 以 base64 形式内联携带图片，替代 `file_id`（二者互斥）。使用 `file_data` 时还可设置 `filename`；`filename` 不能与 `file_id` 同时出现。

***

<a id="documents"></a>

## 文档

上传 PDF、Word、PowerPoint 等文档时，需要把 `purpose` 设为 `text_recognition` 或 `rich_layout_recognition`。表单中的 `purpose` 字段必须写在 `file` 字段之前。

- 文件在上传过程中完成解析，解析成功后才返回文件对象，因此拿到的 `file_id` 都已可用。
- 这样上传的文档不能当作图片使用。在对话请求中引用文档的方式见 [文件解析](https://api-docs.deepseek.com/zh-cn/guides/document_parsing.md#document-qa)。
- 上传的原始文件和解析结果都不支持下载。

限制、错误与计费见 [文件解析](https://api-docs.deepseek.com/zh-cn/guides/document_parsing.md)。

***

<a id="anthropic-compatible-files-api"></a>

## Anthropic 兼容 Files API

同样的文件操作也可通过 Anthropic 兼容端点使用，`base_url` 为 `https://api.deepseek.com/anthropic`。所有请求**必须**带请求头 `anthropic-beta: files-api-2025-04-14`。

端点位于 `/anthropic/v1/` 路径下：Anthropic SDK 设置上述 base URL 时会自动补上 `/v1`；直接用 curl 等裸 HTTP 客户端时需要写完整路径。

这些端点（`POST /anthropic/v1/files`、`GET /anthropic/v1/files`、`GET /anthropic/v1/files/{file_id}`、`DELETE /anthropic/v1/files/{file_id}`）遵循 Anthropic Files API 的形态，与上文 OpenAI 兼容版本存在差异：

|                        | OpenAI 兼容      | Anthropic 兼容                           |
| ---------------------- | -------------- | -------------------------------------- |
| 列表分页                   | `after`        | `after_id` / `before_id`（互斥）           |
| 列表 `limit`             | 1–1000，默认 1000 | 1–1000，默认 20                           |
| 列表 `order` / `purpose` | 支持             | 不支持                                    |
| 列表顶层 `object`          | `"list"`       | 无                                      |
| 文件对象大小字段               | `bytes`        | `size_bytes`                           |
| 文件对象类型字段               | `object`       | `type`                                 |
| `created_at`           | Unix 时间戳（秒）    | RFC 3339 字符串                           |
| 必需请求头                  | 无              | `anthropic-beta: files-api-2025-04-14` |

Anthropic 兼容端点返回的文件对象形如：

```json
{
  "id": "file-api-xxxxxxxxxxxxxxxx",
  "type": "file",
  "size_bytes": 102400,
  "created_at": "2026-01-01T00:00:00+00:00",
  "filename": "image.jpg",
  "mime_type": "image/jpeg"
}
```

使用 `after_id` / `before_id` 游标列出文件：

```bash
curl "https://api.deepseek.com/anthropic/v1/files?limit=20" \
  -H "x-api-key: <DeepSeek API Key>" \
  -H "anthropic-beta: files-api-2025-04-14"
```

```json
{
  "data": [
    {
      "id": "file-api-xxxxxxxxxxxxxxxx",
      "type": "file",
      "size_bytes": 102400,
      "created_at": "2026-01-01T00:00:00+00:00",
      "filename": "image.jpg",
      "mime_type": "image/jpeg"
    }
  ],
  "first_id": "file-api-xxxxxxxxxxxxxxxx",
  "last_id": "file-api-xxxxxxxxxxxxxxxx",
  "has_more": false
}
```

删除文件返回 `{ "id": "...", "type": "file_deleted" }`。

Anthropic 兼容接口的 `purpose` 字段是可选的，不传时按 `user_data` 处理。要上传 PDF、Word、PowerPoint 等文档，需要在 `file` 字段之前传入 `purpose`，取值为 `text_recognition` 或 `rich_layout_recognition`。

***

<a id="limits"></a>

## 限制

| 限制项        | 数值                                                          |
| ---------- | ----------------------------------------------------------- |
| 支持的格式      | 图片：JPEG、PNG、GIF、WebP。其他文件见上文的 `purpose` 表格                  |
| 单个上传文件最大大小 | 图片 64 MiB；PDF、Word、PowerPoint 等文档 100 MiB；纯文本、表格与电子书 32 MiB |
| 文件名最大长度    | 512 字节                                                      |
| 单用户最大存储空间  | 25 GiB                                                      |
| 单用户最大存储文件数 | 10000                                                       |
| 文件有效期范围    | 1 小时到 30 天，或不传 `expires_after` 永久有效                         |
