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

● 在多个请求中复用同一张图片，无需重复上传。
● 发送会超过 48 MiB 请求体限制或 32 MiB 单图内联限制的图片（见 图像理解：限制）。

上传的文件与 deepseek-v4-flash-vision-exp 模型配合使用。如何在对话请求中引用已上传的文件，请参考 图像理解。

支持的格式：JPEG、PNG、GIF、WebP。格式由文件实际内容判断。

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

----------------------

上传文件

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

表单字段：

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 才会出现。

----------------------

列出文件

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>"

查询参数：

响应为分页列表：

{
  "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 <DeepSeek API Key>"

----------------------

删除文件

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

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

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

----------------------

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

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

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    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 同时出现。

----------------------

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 兼容版本存在差异：

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: <DeepSeek 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" }。

----------------------

限制

via DeepSeek 新闻