DeepSeek文件解析APIURL 读取Nbility

DeepSeek API 现在能直接读文件和网页吗?先分清上传、解析和读链接

deepseek-flash 从 11 月 13 日起支持文件输入和阅读链接。上传时选哪种解析方式、file_id 怎么在三种协议里引用、多轮为什么反复计输入,以及什么时候该自己解析。

查看接入文档
DeepSeek API 现在能直接读文件和网页吗?先分清上传、解析和读链接

能。deepseek-flash 从 2026 年 11 月 13 日起支持两种方式把外部内容带进对话:把 PDF、Office 文件或图片传到 Files API 拿到 file_id 再引用;或者打开 deepseek_read_url 工具,让模型自己读用户消息里的链接。两者都由服务端完成解析和抓取,你只提交请求、接收结果。

但“支持文件”不等于“把文件塞进 messages 就行”。文档需要先上传、解析成功,才有 file_id;引用之后的内容会留在上下文里,每一轮都按输入 Token 计费。这篇文章按这三步讲清楚。

文件不是一个字段,而是三步

步骤做什么失败会怎样
上传POST /files,用表单字段带上 purpose 和文件上传超过 120 秒返回 408,文件超过 100 MiB 返回 413
解析上传时同步完成,服务端按 purpose 处理超过 120 秒返回 504,解析不完整返回 500
引用在对话请求里引用返回的 file_id超量、格式不对返回 400

关键一点:响应只在解析成功后才返回,期间服务端不发送任何数据。所以客户端、反向代理、网关的超时要按“上传时间 + 解析时间”设置,不能沿用普通的 30 秒。

另一个容易误判的地方:客户端断开不会取消解析。解析成功的话,文件照常保存、照常计费,之后能在 GET /files 里看到。遇到超时先别重传,先查列表。

上传、解析成功、再用 file_id 引用,三步各自的对象

两种解析方式:要不要让模型看到图

purpose 决定模型拿到什么,直接影响回答质量,也影响费用。

purpose模型得到适合的文档
text_recognition只有文字,图表、照片、示意图被丢弃合同、论文、扫描的文字材料
rich_layout_recognition文字,加上按原位置裁出的图带图表的报告、幻灯片、带示意图的说明书

举个例子:一份财报里有一张营收趋势图,用户问“这张图说明了什么”。用 text_recognition,模型只读到正文,只能根据文字回答;用 rich_layout_recognition,模型能看到图,结合正文一起答。

两点限制要记住:

  • 图是解析时自动识别并裁出的,不保证每张都被裁出。没被裁出的图,模型仍然看不到。
  • 裁出的图会占用输入 Token,并计入每个请求的图片数量上限。模型不需要看图时,用 text_recognition 更省。

还有第三种 purpose:user_data。它对应不需要解析的文件——图片、txt/md/csv/json 和源码,以及 XLSX/XLS 表格、EPUB/MOBI 电子书(上传时转成 Markdown,AZW3 和带 DRM 的电子书不支持)。这类上传不计解析费,原始文件最大 32 MiB、文字最大 8 MiB。文档没有说明转换后表格的公式、多工作表和图表会保留到什么程度,用表格做数据问答前,最好先用一份已知答案的小文件试一次。

三种协议怎么引用同一个 file_id

文件属于账号,同一账号下的所有 API Key 都能引用。三种协议只是 block 的形状不同:

Messages(https://api.deepseek.com/anthropic/v1/messages)需要一个 beta 头:

{
  "model": "deepseek-flash",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "document", "source": {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"}},
      {"type": "text", "text": "总结这份文档的要点。"}
    ]
  }]
}

请求头要加 anthropic-beta: files-api-2025-04-14。这里很容易踩坑:用 curl 时路径要写全 /anthropic/v1/messages,而 Anthropic SDK 会自动补 /v1。

Responses 用 input_file,Chat Completions 用 file,两者都不需要额外请求头:

{"type": "input_file", "file_id": "file-api-xxxxxxxxxxxxxxxx"}
{"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"}

只用 file_id,不要传文件内容或 URL。 文档类文件不支持在请求里直接传 base64 或链接,必须走上传流程。文档也不能当作图片引用,放进去返回 400。

反复计费发生在引用,不在上传

费用分两处:

环节计费方式当前价格
上传解析按页,解析成功才计每 1,000 页 1.5 元
对话引用按输入 Token,等于文档解析结果拼进上下文deepseek-flash 输入价,高峰每百万 Token 2 元、空闲时段 1 元

所以一份 150 页的报告,解析费约 0.225 元,这在整笔支出里通常很小。真正占大头的是引用:文档内容会完整留在对话上下文中,每一轮都作为输入重新计费,而且不会静默截断,超过上下文上限直接返回 400。

假设这份报告解析后是 30 万 Token,你问 8 轮:

  • 如果不命中缓存,单看这份文档就是 30 万 × 8 = 240 万输入 Token,高峰时段约 4.8 元。
  • 如果前缀命中缓存,缓存部分按每百万 0.04 元(高峰)计,金额会低一个数量级。

这也是为什么同一个文档在同一会话里反复引用,要确认缓存是否生效。相关背景见T3 Code 用量与账单:看到的数字、API 等价估算和实际结算,本来就是三件事。

单请求还有两条硬限制:最多引用 20 个文档,文字合计 8 MiB。重复引用同一个 file_id 也分别计算,把同一份大文档在一条消息里塞三次,可能直接撞上限。

解析费按页一次性收取,之后每轮引用都按输入 Token 计费

阅读链接:只处理最后一条用户消息

deepseek_read_url 的工作方式和你写一个抓网页的函数不一样:

  • 只有最后一条用户消息里的链接会被检查,最多前 10 个不同的链接,重复的只算一次。模型自己决定读哪几个。
  • 如果同时开了思考模式和 deepseek_web_search,这一轮走深度思考搜索,不单独读链接。想只读链接,就只声明 deepseek_read_url。
  • 每读一页,产生一个 server_tool_use(input.action 为 read_link)和一个 web_fetch_tool_result 块。多个链接会先全部调用,再一起返回结果。
  • 结果里有 URL、标题、发布日期,但正文不在块里:页面内容加密放在 signature 中。多轮对话时要原样传回这个块,否则页面不会恢复到上下文。

失败状态分三种,处理方式不同:

error_code含义
url_not_accessible链接读不到
url_not_allowed不允许读,或页面没过内容安全审核
unavailable服务不可用、页面打不开,或调用未完成

计费按成功抓取的页数算。对于被 url_not_allowed 和 unavailable 替换掉的结果,文档说明仍然计费——也就是说,审核拦下的页面你仍然要为抓取付钱(每 1,000 次 5 元)。所以不要拿它去批量扫不确定是否允许读取的站点。

最后一条用户消息里的链接、最多 10 个、每页一次抓取,正文靠 signature 带回来

什么时候该自己解析

服务端解析省掉了 OCR、切块、拼上下文的活,但不是所有场景都合适:

  • 需要对原文定位:引用要精确到页码和段落时,自己解析并保存原文,才能事后核对。这一要求和PDF 问答的引用链一致。
  • 同一份资料要给很多用户反复用:上传解析结果不能下载,没有可复用的中间产物。把它放进自己的知识库,再做检索,成本比每轮带全文更可控。
  • 需要看多张表或保留格式:user_data 的表格转换只保留文本,图和多表结构会丢,自己转换格式更可靠。
  • 文件本身不能外发:上传即离开你的系统,对方如何处理、保留多久,取决于服务条款和你的账号设置。敏感合同、客户数据应先在内部评估。

反过来,一次性问答、临时读一份外部文档、内部工具里的“把这篇文章总结一下”,直接用服务端能力最短。

另外,今年围绕文件输入的变化不少,Gemini 侧则是另一套规则(只看首表、PPT 转页面图像等),对照见把 Excel 和 PPT 交给 Gemini,它实际看到了什么。两者都提醒同一件事:上传成功不等于模型看到了你以为的内容。

FAQ

上传的文件能下载回来吗? 不能。原始文件和解析结果都不支持下载,自己的系统要保留原件。

文件会保存多久? 默认永久保存。上传时可以传 expires_after[anchor]=created_at 和 expires_after[seconds](1 小时到 30 天)设置过期。账号下最多存 10,000 个文件、共 25 GiB。

为什么上传报了 400,提示 purpose 相关? 文档类文件必须把 purpose 放在 file 字段前面发送。OpenAI Python SDK 默认先发表单字段,不用改;手写 curl 或自建 multipart 时要注意顺序。

同一账号换了 API Key,之前上传的文件还能用吗? 能。文件属于账号,同一账号下的 Key 共享,但只能在这个账号里引用。

通过 Nbility 使用时的现状

Nbility 目前没有 /files 这类文件上传接口,也没有把 deepseek_read_url 作为独立路由暴露出来。直接按官方文档上传文件,需要拿到 DeepSeek 的 API Key 并请求官方地址。

走 Nbility 时,先按接入基础确认可用模型和调用方式;把文件内容转成文本自己拼进 messages 的用法不受影响,但要自己承担解析和长度控制,参考AI API 返回空内容里的重试注意事项。需要模型联网找资料时,DeepSeek 的搜索与抓取能力是另一条路径,见DeepSeek 搜索 API 开放后,研究简报可以把找、读、引用拆开。

相关文章

用 Nbility 跑通你的 Agent 工作流

获取 API Key,统一接入 OpenAI 兼容模型和开发工具。

获取 API Key