Files API
Files API 让你上传文件,之后通过 file_id 引用。可以上传两类文件:
上传的文件与 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) | 在对话请求中引用图片,见 图像理解。纯文本、表格与电子书见 文件解析 |
text_recognition | PDF、Word(DOC、DOCX)、PowerPoint(PPT、PPTX),以及 PNG、JPEG、WebP、GIF、BMP、TIFF 等图片 | 只解析文字,文档里的图不交给模型,见 文件解析 |
rich_layout_recognition | 同上 | 图文混排解析:文字和文档里的图一起交给模型,见 文件解析 |
上传文档时,purpose 须放在 file 字段之前。以 user_data 上传 PDF、Word、PowerPoint 文件会返回 400。
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>"
查询参数:
| 参数 | 说明 |
|---|---|
after | 用于分页的 file_id 游标;返回此文件之后的文件。 |
limit | 返回的文件数量,取值在 1 到 1000 之间。 |
order | 按创建时间排序:asc(默认)或 desc。 |
purpose | 按用途过滤。user_data、text_recognition 或 rich_layout_recognition。 |
响应为分页列表:
{
"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-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 同时出现。
文档
上传 PDF、Word、PowerPoint 等文档时,需要把 purpose 设为 text_recognition 或 rich_layout_recognition。表单中的 purpose 字段必须写在 file 字段之前。
- 文件在上传过程中完成解析,解析成功后才返回文件对象,因此拿到的
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 兼容版本存在差异:
| 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 兼容端点返回的文件对象形如:
{
"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" }。
Anthropic 兼容接口的 purpose 字段是可选的,不传时按 user_data 处理。要上传 PDF、Word、PowerPoint 等文档,需要在 file 字段之前传入 purpose,取值为 text_recognition 或 rich_layout_recognition。
限制
| 限制项 | 数值 |
|---|---|
| 支持的格式 | 图片:JPEG、PNG、GIF、WebP。其他文件见上文的 purpose 表格 |
| 单个上传文件最大大小 | 图片 64 MiB;PDF、Word、PowerPoint 等文档 100 MiB;纯文本、表格与电子书 32 MiB |
| 文件名最大长度 | 512 字节 |
| 单用户最大存储空间 | 25 GiB |
| 单用户最大存储文件数 | 10000 |
| 文件有效期范围 | 1 小时到 30 天,或不传 expires_after 永久有效 |