第11章 Files API：文件上传与管理指南

Files API 让你可以上传图片，之后通过 file_id 来引用它们。推荐在以下场景使用：

• 多请求复用同一张图片，无需重复上传。
• 发送超出 48 MiB 请求体限制或 32 MiB 单图内联限制的图片（参见 Vision: Limits）。

上传的文件配合 deepseek-flash 模型使用。如何在对话请求中引用已上传的文件，参见 Vision。

支持的格式：JPEG、PNG、GIF 和 WebP。格式根据文件实际内容自动识别。

下文示例的 base_url 为 https://api.deepseek.com。

Upload a File​

通过 multipart/form-data 请求上传文件，接口为 POST /files。单个文件最大 64 MiB，上传必须在 10 分钟内完成。

表单字段：

字段	必填	说明
file	是	要上传的图片文件。
purpose	是	必须为 user_data。
expires_after[anchor]	否	如提供，必须为 created_at。需与 expires_after[seconds] 搭配使用。
expires_after[seconds]	否	文件有效期（秒），取值 3600 到 2592000（1 小时到 30 天）。两个 expires_after 字段都不填则文件永久保存。

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

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

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

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

只有在上传时设置了有效期，响应中才会包含 expires_at。

List Files​

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

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

查询参数：

参数	说明
after	用于分页的 file_id 游标，返回此文件之后的文件。
limit	返回的文件数量，取值 1 到 1000。
order	按创建时间排序：asc（默认）或 desc。
purpose	按 purpose 过滤，目前仅支持 user_data。

响应是一个分页列表：

{
  "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
}
获取文件信息​ info = client.files.retrieve("file-api-xxxxxxxxxxxxxxxx")
print(info.filename, info.bytes)
curl https://api.deepseek.com/files/file-api-xxxxxxxxxxxxxxxx \
-H "Authorization: Bearer "
删除文件​ client.files.delete("file-api-xxxxxxxxxxxxxxxx")
curl -X DELETE https://api.deepseek.com/files/file-api-xxxxxxxxxxxxxxxx \
-H "Authorization: Bearer "
{
"id": "file-api-xxxxxxxxxxxxxxxx",
"object": "file",
"deleted": true
}
在聊天请求中使用已上传的文件​ 通过 file 内容块引用返回的 file_id： response = client.chat.completions.create(
model="deepseek-flash",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "What is in this image?"},
{"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
],
}
],
)
print(response.choices[0].message.content)
文件归属于你的 API 密钥，可被任一 API 体系引用。请注意，若要通过 Anthropic 兼容的 /messages 端点引用文件，必须携带 `anthropic-beta: files-api-2025-04-14` 请求头。 与内联（base64）图片不同，通过 `file_id` 引用的文件不受单张 32 MiB 的限制——单次请求中，`file_id` 图片最大可达 64 MiB。 文件块也可以 `file_data` 字段内联传输 base64 图片，替代 `file_id`（两者互斥）。使用 `file_data` 时可同时设置 `filename`；但若使用 `file_id`，则不允许指定 `filename`。 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 后缀；但若使用纯 HTTP 客户端（如 curl），则需手动写完整路径。 端点包括（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`（互斥） 列表上限 | 1–1000，默认 1000 | 1–1000，默认 20 列表排序 / 用途 | 支持 | 不支持 列表顶层对象 | `"list"` | 无 文件对象大小字段 | `bytes` | `size_bytes` 文件对象类型字段 | `object` | `type` `created_at` | Unix 时间戳（秒） | RFC 3339 字符串 必需请求头 | 无 | `anthropic-beta: files-api-2025-04-14` Anthropic 兼容端点返回的文件对象示例： {
"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` 游标列出文件： curl "https://api.deepseek.com/anthropic/v1/files?limit=20" \
-H "x-api-key: " \
-H "anthropic-beta: files-api-2025-04-14"
{
"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" }。 限制​ 限制项值支持格式JPEG、PNG、GIF、WebP单个文件上传大小上限64 MiB文件名最大长度512 个字符每用户存储空间上限25 GiB每用户可存储文件数量上限10000文件有效期1 小时至 30 天，或永久（不传 expires_after）