指南 / DeepSeek Files API
DeepSeek Files API (2026)：限制、上传与 file_id 实战
DeepSeek 于 2026 年 8 月 21 日随视觉模型悄然上线了首个文件端点——这也让许多旧指南失效（部分仍声称 DeepSeek 的 API “没有文件上传路由”）。本指南包含已验证的各项限制、curl 与 Python 的上传及引用示例，以及何时使用文件而非 base64。
DeepSeek Files API 仅需上传一次图片即可返回 file_id，供在对话中引用。
上传时指定 purpose="user_data"；单个文件最大支持 64 MiB（10 分钟上传窗口期）；单用户存储上限为 25 GiB / 10,000 个文件；保留时间为 1 小时至 30 天，若省略 expires_after 则永久保留。
在 deepseek-v4-flash-vision-exp 对话中通过 {"type":"file","file_id":...} 块引用文件——请求中的 file_id 图片最大可达 64 MiB，而内联图片上限为 32 MiB。若使用 Anthropic 兼容端点，请添加 anthropic-beta: files-api-2025-04-14 请求头。
限制一览
| 限制项 | 数值（官方文档，2026-08-21） |
|---|---|
| 支持格式 | JPEG、PNG、GIF、WebP —— 根据文件内容检测，而非扩展名 |
| 单文件 | 最大 64 MiB；上传必须在 10 分钟内完成 |
| 单用户 | 25 GiB 存储空间；最多存储 10,000 个文件 |
| 保留时间 | 1 小时至 30 天，或永久保留（省略 expires_after） |
| 用途 | 必须为 user_data（唯一支持的用途，亦用于列表筛选） |
| 请求内大小 | 单次请求中 file_id 图片最大 64 MiB；内联 base64/URL 图片上限为 32 MiB |
| API 兼容性 | 兼容 OpenAI 与 Anthropic；Anthropic /messages 需要携带 files-api beta 请求头 |
来源：官方 Files API 指南，查阅于 2026-08-21。
一次上传，永久引用（好吧，最多 30 天）
上传截图并获取 file_id：
curl https://api.deepseek.com/files \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-F "purpose=user_data" \
-F "file=@dashboard.png"随后在 vision-exp 对话中引用它——无需 base64 数据，后续轮次无需重新上传：
curl https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-d '{
"model": "deepseek-v4-flash-vision-exp",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "Which metric regressed in this dashboard?"},
{"type": "file", "file_id": "file-api-xxxx"}
]
}]
}'使用 OpenAI SDK 的 Python 示例——先上传，后对话：
from openai import OpenAI
client = OpenAI(api_key="YOUR_KEY", base_url="https://api.deepseek.com")
f = client.files.create(file=open("dashboard.png", "rb"), purpose="user_data")
resp = client.chat.completions.create(
model="deepseek-v4-flash-vision-exp",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Which metric regressed?"},
{"type": "file", "file_id": f.id},
],
}],
)
print(resp.choices[0].message.content)- 内联替代方案：文件块可携带
file_data（base64）而非file_id——两者为互斥字段；filename仅能与 file_data 配合使用。 - Anthropic 风格技术栈：携带
anthropic-beta: files-api-2025-04-14请求头时，相同的文件块在 /messages 上同样有效。
何时使用文件 vs base64 vs URL
| 方式 | 大小上限 | 最佳适用场景 |
|---|---|---|
| base64 内联 | 32 MiB | 进程内生成的单次图片；代码编写最简单 |
| 外部 URL | 32 MiB，8,192 字符 URL，60 秒抓取超时 | 公开托管的图片；完全无需上传步骤 |
| Files API | 64 MiB | Agent 截图循环、重复引用的图片，以及任何跨轮次复用的场景 |
FAQ
我看到有人说 DeepSeek 没有文件端点——这是新上线的吗？
在 2026 年 8 月 21 日之前确实如此——早期指南中“无 /v1/files 路由，需自行提取文本”的描述在当时是准确的，但现在已经过时。Files API 是随视觉模型发布一同上线的。
我可以上传 PDF 或文档吗？
不能——Files API 目前仅支持图片格式（JPEG/PNG/GIF/WebP）。对于 PDF，需在调用方将页面渲染为图片，然后再上传或内联传递。
文件能保存多久？
通过 expires_after 可设置为 1 小时至 30 天，若省略则永久有效——均在 25 GiB / 10,000 个文件的配额范围内。
非视觉模型可以使用文件吗？
文件块仅被 deepseek-v4-flash-vision-exp 支持；纯文本版 V4-Flash/V4-Pro 仍仅支持文本。请勿向文本模型传递文件引用。