把 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_id | PDF、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.action | name | kind | 结果 |
|---|---|---|---|
search | deepseek_web_search | 思考时为 deep_search,否则 search | web_search_tool_result |
open_page | deepseek_web_search | deep_search | web_fetch_tool_result。data 是空字符串。没有 signature |
find_in_page | deepseek_web_search | deep_search | 形状相同。title 为 null。不计费 |
read_link | deepseek_read_url | read_link | web_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_score | 0 到 3。指南把 1.5 及以上视为高质量 |
authority | 0 到 4。−1 表示未知。3 及以上为高权威 |
snippet / summary | 短的给界面,长的给模型 |
content | need_content 不为 true,或页面没有内容时,为空字符串 |
date | RFC 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 |
|---|---|
| Messages | stop_reason 为 refusal,stop_details.type 为 refusal。非流式会去掉思考和答案文本,保留工具块和一个空的 text 块 |
| Responses | status 为 incomplete,incomplete_details.reason 为 content_filter。output 只保留已执行的 web_search_call |
| Chat | finish_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
- 请求体是
deepseek-flash。Messages 的工具同时有type和name。想要带引用的搜索时,思考为disabled。 - 面向公众的应用发送
safety_check.levelhigh。这些调用的response_format和text.format保持text。 - 解析器用
tool_use_id和kind配对,并把signature留到下一轮。 - 账单使用
tool_search、tool_fetch、tool_image_search,加上缓存未命中输入、缓存命中输入和输出。不要把web_search_requests加进去。 - 独立接口的
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。