DeepSeek 11 月 13 日开放应用工具之后,deepseek-flash 的 JSON 该如何声明 deepseek_web_search、deepseek_read_url 和 safety_check,并把 tool_search 与 token 分开记账?

只改模型名不会打开搜索。tools、thinking 和 safety_check 决定 JSON。计费次数是 tool_search。

把 model 写成 deepseek-flash 并不会打开搜索。 2026 年 11 月 13 日,DeepSeek 把聊天应用背后的工具放到了 API 上。模型名 deepseek-flash 对应 DeepSeek-V4.1-Flash-1017。旧名 deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 仍会转到这里,并按 Flash 价格计费。上下文 100 万 token。最大输出 38.4 万。思考模式是默认值。

本文写于 2026 年 11 月 16 日,依据 11 月 13 日的更新日志、网页工具指南、Search 与 Fetch 指南、安全指南和价格页。三天前我们写过 Gemini 4 Carbon 的 usage。这里会改请求和账单的字段是 tools、thinking、safety_check 和 usage.server_tool_use。

11 月 13 日开放了什么

同一个模型在三个端点接受这些工具。Messages 是 POST https://api.deepseek.com/anthropic/v1/messages,头为 x-api-key。Responses 是 POST https://api.deepseek.com/responses。Chat Completions 是 POST https://api.deepseek.com/chat/completions。后两个用 Authorization: Bearer。Search、Fetch、OCR、ASR、TTS 也可以单独调用。搜图不在 POST /v1/tools/search,只在 deepseek_web_search 里面。

能力打开它的 JSON返回什么
网页搜索deepseek_web_search,思考关闭模型自行决定是否搜索,并给出引用
深度思考搜索deepseek_web_search,思考打开search、open_page、find_in_page,大约 20 次调用
读链接deepseek_read_url只看最后一条用户消息,最多前 10 个不同 URL
安全safety_check.level = high审查输入和输出。面向公众的服务需要打开
文件Files API 的 file_idPDF、Office 和图片先解析,再进入对话

三个端点的请求 JSON

Messages 要把工具名写两遍:type 和 name。Responses 和 Chat 只写 type。tool_choice 不能点名这些工具,否则 400,deepseek_web_search cannot be forced。tool_choice 为 none 会关掉全部已声明的网页工具,包括读链接。Responses 和 Chat 里,required 被当成 auto。

不要传 allowed_domains、blocked_domains 或 user_location。不要把同一个工具声明两次。不要再混入别的服务端工具。错误信息写明,其他工具目前不能与 deepseek_web_search、deepseek_read_url、safety_check 或 title 一起用。Responses 上,web_search 工具以及非 text 的 text.format 都会 400。Chat 上,web_search_options 以及非 text 的 response_format 都会 400。结构化 JSON 和这些网页工具不能放在同一次请求里。把你自己的 schema 放到下一次调用。见 什么是结构化输出。

关闭思考是带引用的搜索。打开思考是深度思考搜索。两者同时打开时,这一轮不会再跑 deepseek_read_url。读链接发生在思考关闭时,或只声明了 deepseek_read_url 时。Messages 和 Chat 用 thinking.type 的 disabled 或 enabled。Responses 文档里,深度思考搜索的示例把 reasoning.effort 设为 high。

{
  "model": "deepseek-flash",
  "thinking": {
    "type": "disabled"
  },
  "safety_check": {
    "level": "high"
  },
  "tools": [
    {
      "type": "deepseek_web_search",
      "name": "deepseek_web_search"
    },
    {
      "type": "deepseek_read_url",
      "name": "deepseek_read_url"
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "What changed in the DeepSeek API on 13 November 2026?"
    }
  ]
}

Responses,深度思考搜索:

{
  "model": "deepseek-flash",
  "reasoning": {
    "effort": "high"
  },
  "safety_check": {
    "level": "high"
  },
  "tools": [
    {
      "type": "deepseek_web_search"
    },
    {
      "type": "deepseek_read_url"
    }
  ],
  "input": "Which official page states the height of Tokyo Tower?"
}

块、kind 和引用

Messages 里,每次调用是一个 server_tool_use 块加一个结果块。用 tool_use_id 配对。流式响应里,两种块都在 content_block_start 一次到齐。最终 usage 读 message_delta。message_start 里的 usage 只覆盖第一步推理。

input.actionnamekind结果
searchdeepseek_web_search思考时为 deep_search,否则 searchweb_search_tool_result
open_pagedeepseek_web_searchdeep_searchweb_fetch_tool_result。data 是空字符串。没有 signature
find_in_pagedeepseek_web_searchdeep_search形状相同。title 为 null。不计费
read_linkdeepseek_read_urlread_linkweb_fetch_tool_result,另有 signature

搜图把 kind 设为 image_search 或 deep_image_search。queries 是空数组。结果里可能多一个仅供展示的 image_url。Messages 的引用在 text 块上,类型为 web_search_result_location。cited_text 是该块的答案文本,不是网页原文。encrypted_index 始终是空字符串。一个块里同一个 URL 最多出现一次。流式里以 citations_delta 到达。

Responses 把调用放在 web_search_call,带 kind 和 action。答案是带 url_citation 标注的 output_text。start_index 和 end_index 按 Unicode 码位计数。Chat 把调用放在 message.server_tool_calls。每一步有 reasoning_content 和 calls。message.content 里没有引用标记。引用在 message.annotations。message.reasoning_content 只有最后一步。

用过这些工具的回复不能续写,API 返回 400,并要求重发上一次请求。下一轮要把助手内容原样传回,包括 kind 和 signature。搜索摘要和更早的思考不会进入后续上下文,只有答案文本会。读到的页面从 signature 恢复。read_link 的 data 始终是空字符串。丢掉 signature 请求仍会成功,但页面不在了。抓取失败的 error_code 是 url_not_accessible、url_not_allowed、unavailable。url_not_allowed 也包括没通过安全审查的页面。

一条 Responses 搜索项:

{
  "type": "web_search_call",
  "id": "srvtoolu_s_00_3f2a9c",
  "status": "completed",
  "kind": "search",
  "action": {
    "type": "search",
    "queries": [
      "DeepSeek API 13 November 2026"
    ],
    "sources": [
      {
        "type": "url",
        "url": "https://example.com/news",
        "title": "Change log",
        "snippet": "Web search and URL reading are now API tools.",
        "published_at": "2026-11-13T00:00:00+00:00"
      }
    ]
  }
}

独立的 Search 与 Fetch JSON

由代码而不是模型决定何时搜索时,调用原始 JSON API。Search 是 POST https://api.deepseek.com/v1/tools/search。query 必填,1 到 128 个字符,不能全是空白。count 为 1 到 50,默认 10。ori_question 可选,同样 1 到 128 个字符。localization 是可选 IP。need_content 默认 false。未知字段会被忽略。可以原样传过去的运算符:site:、-site:、-、-"..."、"..."、lang:、after:、before:。

{
  "query": "DeepSeek site:api-docs.deepseek.com after:2026-11-01",
  "count": 10,
  "need_content": false
}

Fetch 是 POST https://api.deepseek.com/v1/tools/fetch。唯一字段是 url,最长 8,192 个字符,必须是带主机的 HTTP 或 HTTPS,不能带用户名或密码。响应是 title 和 Markdown 的 content。没有标题时 title 是空字符串。

{
  "url": "https://api-docs.deepseek.com/updates"
}
字段要存下来的含义
rerank_score0 到 3。指南把 1.5 及以上视为高质量
authority0 到 4。−1 表示未知。3 及以上为高权威
snippet / summary短的给界面,长的给模型
contentneed_content 不为 true,或页面没有内容时,为空字符串
dateRFC 3339 的 UTC 时间,或 null

file_id、OCR 和语音 JSON

文件输入分两步。POST https://api.deepseek.com/files,purpose 必须写在 file 前面。text_recognition 丢掉图表。rich_layout_recognition 把图裁进正文,并消耗图像 token。文件对象只在解析完成后返回。id 形如 file-api-...。客户端断开不会取消随后成功的解析:文件会被保存并计费。原文和解析结果都不能下载。Chat Completions 这样引用:

{
  "role": "user",
  "content": [
    {
      "type": "file",
      "file_id": "file-api-xxxxxxxxxxxxxxxx"
    },
    {
      "type": "text",
      "text": "Summarize the revenue chart."
    }
  ]
}

Messages 需要头 anthropic-beta: files-api-2025-04-14,以及 source.type 为 file 的 document 块。Responses 用 input_file 和 file_id。解析过的文档不能当成图片块。也不能在对话请求里直接贴文件字节或文件 URL。一次请求最多引用 20 个文档,正文合计最多 8 MiB。后续轮次会保留完整解析结果。太长则 400。不会悄悄截断。

限制:PDF、Word、PowerPoint 和常见图片,按文件内容识别格式。100 MiB,更大返回 413。1,000 页。上传 120 秒,否则 408。解析 120 秒,否则 504。每个账号同时进行的文档上传为 15 个。加密文件返回 400。纯文本、csv、json、源代码、xlsx、xls、epub、mobi 用 purpose user_data,不按页计费。这些文件最大 32 MiB,文本最大 8 MiB。不支持 AZW3 和带 DRM 的电子书。

解析成功才按页计费,每 1,000 页 0.225 美元,只收一次。之后的对话按输入 token 计费,不再按页。OCR 同样是这个页价,端点 POST /v1/tools/ocr,不进入 Files API。它是 multipart,字段为 file 和 purpose,不是 JSON 体。ASR 是 multipart 音频,不是 JSON。TTS 是 JSON,POST /v1/tools/tts:

TTS 标价为每 1 万字符 0.45 美元,公布的限时价为 0.225 美元。一个汉字算 2 个字符,其他字符算 1。声音为 stella(默认)和 tide。没有语言字段。ASR 标价为每小时音频 0.116 美元,限时 0.058 美元,按秒计费,不足 1 秒按 1 秒。价格页没有写半价的结束日期。

{
  "text": "Hello from DeepSeek.",
  "voice_id": "stella",
  "format": "wav",
  "filter_markdown": true
}

safety_check 和拒绝 JSON

公众能访问的服务要把 safety_check 设为 {"level":"high"}。low 等于省略该字段。其他 level 返回 400。这个参数不代替你自己的内容审查、备案和标识义务。输入未通过返回 400 Content Exists Risk。这些输入 token 仍会计费,按缓存命中价。模型生成结束后连接不会马上关掉,服务端还要审查完整输出。已经流出的文本收不回来。把已展示的答案换成你自己的拒绝提示。拒绝前消耗的 token 会计费。审查 token 含在输出 token 里,并单独出现在 Messages 和 Responses 的 usage.output_tokens_details.safety_tokens,或 Chat 的 usage.completion_tokens_details.safety_tokens。被拦截的图片可能给出路径,例如 messages.1.content.0,位置在 stop_details.explanation、refusal 内容项或 message.refusal。声明了网页工具但没写 safety_check 的请求,仍可能以拒绝结束。

API拒绝时的 JSON
Messagesstop_reason 为 refusal,stop_details.type 为 refusal。非流式会去掉思考和答案文本,保留工具块和一个空的 text 块
Responsesstatus 为 incomplete,incomplete_details.reason 为 content_filter。output 只保留已执行的 web_search_call
Chatfinish_reason 为 content_filter。content 是空字符串。annotations 省略。server_tool_calls 保留,每一步的思考被清空

记 tool_search,不要记 web_search_requests

token 和工具分开记账。Flash 价格按每 100 万 token。尖峰时段是周一到周五 UTC 01:00–04:00 和 06:00–10:00,不含中国法定节假日。其余时间都是离峰,周末和中国法定节假日全天离峰。离峰是尖峰的一半。cache_creation_input_tokens 始终为 0。

时段缓存命中 / 100 万缓存未命中 / 100 万输出 / 100 万
离峰$0.003$0.15$0.60
尖峰$0.006$0.30$1.20

搜索和网页抓取都是每 1,000 次成功调用 0.75 美元,无论是模型调用工具,还是你自己调用 /v1/tools/search 或 /v1/tools/fetch。有结果的工具搜索按 query 计费,三条 query 算三次。count 不改变 Search API 的单价。HTTP 200 且 results 为空数组时不计费。Fetch 只有在返回页面内容时才计费。安全审查随后把页面换成 url_not_allowed 或 unavailable 的,这次抓取已经发生,仍要计费。深度思考搜索里再次打开同一页不计费。find_in_page 不计费。

Search 每个账号每秒 100 次。Fetch 为 25 次,另外还有每个域名的上限。上限按账号而不是按密钥,并且与 Flash 的 2,500 并发分开。网页工具指南里,一次带两条 query 的引用搜索报告 web_search_requests 为 1、tool_search 为 2。要存的是 tool_search、tool_fetch、tool_image_search。不要再把 web_search_requests 加进去。Responses 和 Chat 在这三项都是 0 时会省略 server_tool_use 里的这一组。thinking_tokens 在打开思考时出现。safety_tokens 在 safety_check 为 high 时出现。两者都已经包含在输出 token 总数里。

如果 HTTP 状态已经是 200,生成中途失败,响应体是错误加 usage。Messages 流式以 error 事件结束,后面没有 message_delta。要检查响应体。SDK 不会因为状态 200 抛异常。下面是那次两条 query 的公开示例。thinking_tokens 和 safety_tokens 不在这个对象里。思考打开时,或 safety_check 为 high 时,它们会单独出现,并且已经含在 output_tokens 里:

{
  "input_tokens": 1905,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 0,
  "output_tokens": 72,
  "service_tier": "standard",
  "server_tool_use": {
    "web_search_requests": 1,
    "web_fetch_requests": 0,
    "tool_search": 2,
    "tool_fetch": 0,
    "tool_image_search": 0
  }
}

上线前要核对的 JSON

  1. 请求体是 deepseek-flash。Messages 的工具同时有 type 和 name。想要带引用的搜索时,思考为 disabled。
  2. 面向公众的应用发送 safety_check.level high。这些调用的 response_format 和 text.format 保持 text。
  3. 解析器用 tool_use_id 和 kind 配对,并把 signature 留到下一轮。
  4. 账单使用 tool_search、tool_fetch、tool_image_search,加上缓存未命中输入、缓存命中输入和输出。不要把 web_search_requests 加进去。
  5. 独立接口的 query 为 1 到 128 个字符。count 为 1 到 50。空结果不是一笔费用。

在本地用 JSON 校验、JSONPath($.usage.server_tool_use.tool_search)和 JSON 对比 核对上一份请求。数据不会上传。

常见问题

打开 thinking 会改变搜索吗?

会。thinking.type 为 disabled 时是一次带引用的网页搜索,kind 为 search。enabled 是深度思考搜索:search、open_page、find_in_page,大约 20 次调用,kind 为 deep_search。思考模式是默认值。思考和 deepseek_web_search 同时打开时,这一轮不会再跑 deepseek_read_url。

tool_choice 能强制 deepseek_web_search 吗?

不能。点名这个工具会返回 400,deepseek_web_search cannot be forced。是否搜索由模型决定。tool_choice 为 none 会关掉已声明的网页工具,包括读链接。Responses 和 Chat 里,required 被当成 auto。

账单该用 web_search_requests 吗?

不该。这个数包含错误,只用于展示。计费字段是 tool_search、tool_fetch、tool_image_search。网页工具指南里,一次搜索块带两条 query,报告 web_search_requests 为 1、tool_search 为 2。有结果的搜索按 query 条数计费。空结果或失败不计费。

POST /v1/tools/search 能搜图吗?

不能。搜图只在 deepseek_web_search 里。kind 为 image_search 或 deep_image_search,queries 是空数组。每张图算 1 次搜索,模型在图上圈出的每个区域再算 1 次。

面向公众的服务该怎么写安全检查?

DeepSeek 写明面向公众的服务要打开 safety_check,level 为 high。low 等于不写这个字段。输入未通过返回 400 Content Exists Risk,这些输入 token 仍按缓存命中价计费。拒绝的答案是 stop_reason 为 refusal,Responses 为 incomplete 且 content_filter,Chat 为 finish_reason content_filter。

搜过的回复能续写吗?

不能。用过 deepseek_web_search 或 deepseek_read_url 的回复会返回 400。请重发上一次请求。下一轮要把助手块原样传回,包括 kind 和 signature。没有有效 signature 时请求仍会成功,但页面不会回到上下文。

小结

11 月 13 日的工具改的是请求、你必须存下的块,以及账单上的另一行。 在 deepseek-flash 上声明 deepseek_web_search 和 deepseek_read_url。带引用的搜索关掉思考,深度思考搜索打开思考。面向公众的应用把 safety_check.level 设为 high。记 tool_search,不要记 web_search_requests。