浏览 REST API 参考

终结点：POST https://api.microsoft.ai/v3/browse

示例请求：

curl -X POST "https://api.microsoft.ai/v3/browse" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    "query": "How fast is Web IQ",
    "contentFormat": "passage",
    "maxLength": 3000,
    "liveCrawl": "fallback",
    "language": "en",
    "region": "US"
  }'

段落是用于地面的建议格式。 具有完整文档访问权限的应用程序可以通过设置为contentFormattext或htmlmarkdown设置来请求整个页面。 请参阅 段落和内容格式。

Parameters

参数	Required	类型	Default	Description
url	是	字符串	-	要浏览的网页的 URL。
查询	必需 passage	字符串	-	用于从页面中选择段落的查询，最多 1000 个字符。 请求 passage 需要不为空的查询。 对于其他格式， query 是可选的。 长度超过 1000 个字符的值返回 HTTP 400。 此限制独立于 maxLength.
maxLength（最大长度）	否	整数	3000 （具有完整文档访问权限的 10000）	最大字符 content数，介于 1 到 500000 之间。 该范围之外的值返回 HTTP 400。 如果没有完全的文档访问权限， content 则最多包含 3000 个字符，并且较大的值上限为 3000。
liveCrawl	否	字符串	无	控制实时爬网行为。 支持的值：“none”（仅返回索引内容，没有实时爬网）和“回退”（如果在索引中找不到 URL，则请求实时爬网）。 对于“none”，如果在索引中找不到 URL，API 将返回 404（找不到 URL）。 注意： 实时爬网受发布者礼貌限制和可用性的约束;“回退”不能保证实际爬网。
includeWebLinks	否	boolean	false	包括来自页面的出站超链接。 对于段落内容，忽略。
renderDynamicPages	否	boolean	false	为动态内容屏幕截图启用 JavaScript 呈现。 仅当 liveCrawl 设置为“回退”时才有效。
includeImageLinks	否	boolean	false	包括页面中的图像 URL。 对于段落内容，忽略。
语言	否	字符串	“en”	语言代码（2 字母 ISO 639-1）。 有关完整列表，请参阅 “支持的语言 ”。
区域	否	字符串	"US"	区域代码（2 字母国家/地区代码）。 有关完整列表，请参阅 “支持的区域 ”。
contentFormat	否	字符串	具有完整文档访问权限的“段落”（“html”）	“段落”返回与页面最相关的 query 部分（建议用于地面）。 “text”、“html”和“markdown”返回完整文档，仅适用于具有 完整文档访问权限的应用程序;如果没有它，则返回 HTTP 403 （AuthContentFormatForbidden）。 请参阅 段落和内容格式。

对于通道请求，设置为 contentFormat “通道”并发送非空 query。 如果省略 contentFormat，“段落”是默认值，除非应用程序具有完整的文档访问权限，其中默认值为“html”。 没有 query 返回 HTTP 400 的段落请求（HandlerInvalidInput）。

通道请求

通道请求受普通请求验证的约束，以及以下内容：

• query 必须包含空格以外的文本，并且最多包含 1000 个字符。 否则，请求将返回 HTTP 400 （HandlerInvalidInput）。
• liveCrawl 必须为“none”或“fallback”。

通过 MCP，这些失败会返回 HTTP 200，并返回包含原始请求 ID 的工具错误（result.isError: true）。 段落在现有 content 字段中返回;响应的形状与其他内容格式相同。

段落内容

段落是请求页的查询焦点提取。 服务不从头返回页面，而是选择与页面最相关的 query 部分，并在字段中返回它们 content 。

• 选择： 页面划分为按相关性 query排名的段。 在达到预算之前 maxLength ，会选择排名最高的细分市场。
• 排序： 所选段按原始页面顺序返回，而不是按排名顺序返回。 非相邻段由 ....
• 段边界：段 由长度而不是句子或段落定义，因此摘录可以开始或结束中句。 将段落显示为摘录，并使用源 url 进行归因。
• 格式： 段落内容为纯文本。 标记、超链接和图像引用不包含在 content内。
• 长度：content 永远不会超过 maxLength 字符。 默认值 maxLength 为 3000，不具有完整文档访问权限，具有完全文档访问权限的 10000。 短页可以完整返回。
• 回退： 如果相关性选择暂时对请求不可用，服务会以纯文本形式返回页面的开头，截断为 maxLength。
• 内容限制： 发布者和网站策略（如机器人指令和付费墙规则）在选择之前应用。 仅从可以为页面返回的内容中选择段落。
• 其他行为： URL 解析、带有“回退”的实时爬网、挂起的爬网（HTTP 202）响应、响应字段（例如 title， crawledAt和 isAdult错误响应）与其他内容格式相同。

请求标头

领域	类型	Description
主持人	字符串	适用于 Microsoft AI API 的主机：api.microsoft.ai.
x-apikey 或 授权	字符串	API 密钥或Entra ID访问令牌进行身份验证。
Content-Type	字符串	请求正文的 MIME 类型。 使用 application/json。

响应

领域	类型	Description
url	字符串	网页的 URL，或爬网挂起时要重试的 URL。
title	字符串	网页的标题。
内容	字符串	网页（即地面）的提取内容。 对于段落请求，选择的 query段落。
最后更新时间	字符串	网页的上次更新时间遵循ISO8601格式。
crawledAt	字符串	网页的最后一个已爬网日期遵循ISO8601格式。
traceId	字符串	用于调试的跟踪 ID。
retryAfter	字符串	最早重试的时间，作为 ISO 8601 UTC 时间戳（例如）。 "2026-10-30T01:01:00Z" 当按需爬网正在进行（202）和某些错误时出现。
isAdult	boolean	指示网页是否包含成人内容。

Note

title、content、isAdultlastUpdatedAt和crawledAt字段仅在成功的 （200） 响应中存在。 重试 （202） 响应会省略它们。

示例：段落请求和响应

上面的示例中的请求返回如下所示的响应。 服务选择了页面的非相邻段，并将它们联接在一起 ...。

{
  "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
  "title": "Why AI agents need external grounding | Microsoft Web IQ",
  "content": "Why AI agents need external grounding | Microsoft Web IQ Microsoft Community Hub Azure Microsoft Developer Community Blog nodeTitle minReadText Why AI Agents Need External Grounding bkingms Microsoft Oct 18, 2026 Earlier this year, we introduced Microsoft Web IQ, a suite of AI-native web search and grounding APIs that gives LLMs, AI agents, and applications access to current, relevant web information. This post explores why web grounding is becoming a foundational layer of AI, how it helps deliver answers customers can use and verify, and how we’re addressing the quality, speed, and efficiency developers need. -- When customers ask an AI agent or application for help, the answer may do more than inform them—it may shape a recommendation, trigger a workflow, or guide an action. If that answer relies on... ... an engineering approach that treats quality, speed, and token efficiency as a connected problem. You can read more on our engineering approach here. Highest grounding satisfaction. On a 3,000 query blind test sampled from production traffic, Web IQ scored 79.05 against 75.70 for the next best service and more than 14 points ahead of the lowest. It gets there by returning more complete, structured context drawn from web, news, images, and video. What your users see is answers that hold up: more accurate, more consistent, and properly attributed. In the domains where source quality, freshness, and attribution drive the decision, that is the difference between an agent people act on and one they quietly double check. 2.5x faster than today's best alternative. P95 latency measured 164 milliseconds across five datacenter regions, against 406 for the closest competitor and 2,090 for the slowest. Latency compounds in agent workloads, because a multi-step chain pays the retrieval cost at every hop. Cutting it at each step keeps workflows moving and keeps interactive agents feeling interactive instead of batch. Highest quality answers with the fewest tokens. Web IQ sits on a new Pareto curve of efficiency, reaching peak quality at around 40,000 tokens per query while competing services spend 60,000 to 100,000 to score lower. Prioritizing the most relevant passages and cutting unnecessary context reduces both token spend and reasoning time, and those savings compound across high volume production workloads. Most web search APIs force a tradeoff — fast or accurate, cost-efficient or complete. Web IQ is delivers across the board: industry-leading quality, fastest performance, and fewest tokens per query — all in an enterprise-ready solution. For teams evaluating Web IQ, those results provide a starting point. We recommend testing your own questions, sources, models, and end-to-end workflows to understand how retrieval quality and efficiency translate into customer outcomes. Grounding satisfaction is a benchmark score, not an accuracy percentage, and retrieval latency is only one part of the time required to complete a task. Within Microsoft IQ,...",
  "isAdult": false,
  "lastUpdatedAt": "2026-10-18T00:00:00",
  "crawledAt": "2026-10-29T07:44:00Z",
  "traceId": "6ae4fd995e3d425f847c07c2f0839e38"
}

错误代码

状态代码	错误类别	Description	常见原因
200	成功	请求成功。	-
202	Accepted	已接受处理请求（实时爬网）。	正在进行的按需爬网
400	错误的请求	无效的请求参数。	缺少必填字段、无效参数值、格式不正确的 JSON、段落请求的缺失或空白query
401	Unauthorized	身份验证失败或缺失。	API 密钥无效，缺少 x-apikey 标头
403	禁止	有效的凭据，但无法满足请求。	API 密钥缺少所需的权限、受策略阻止的 URL、经过筛选的内容、texthtml或markdown请求且没有完全文档访问权限
404	未找到	找不到文档。	URL 无效或不可访问
410	不存在 (Gone)	需要 HTTPS。	通过 HTTP 而不是 HTTPS 发出的请求
415	不支持的媒体类型	不支持内容类型。	缺少或不正确的内容类型标头
429	请求过多	超出速率限制或按需爬网限制。	时间范围内请求过多或实时爬网请求过多
430	按需爬网过多	过多的按需爬网（旧错误代码）。	过多的实时爬网请求
500	内部服务器错误	意外的服务器错误。	临时服务器问题
503	服务不可用	服务暂时不可用。	维护或临时中断
504	网关超时	请求已超时。	上游服务超时
520	内容处理失败	检索了页面，但无法生成任何可用内容。	文档处理失败或超时，或动态呈现超时
523	已取消爬网	由于网站爬网配额有限，爬网未生成内容。	源主机的有限爬网配额
524	爬网超时	爬网未生成内容，因为它超时。	远程主机超时

通道请求错误

这些错误适用于段落请求。 当“段落”是默认格式时，它们也适用。

条件	HTTP 状态	错误代码
query 缺少、空白或长度超过 1000 个字符	400	HandlerInvalidInput
没有完整文档访问请求 text的应用程序， html或 markdown	403	AuthContentFormatForbidden

粒度错误代码

默认情况下，为“浏览”启用粒度错误代码。 它们确定无法返回页面的特定原因，例如内容筛选、缺少的文档或爬网失败，并包括重试指南（如果适用）。 无需选择加入或支持请求。

有关代码的完整列表和建议的操作，请参阅 “浏览 API 特定错误”。

有关详细的错误处理指南，请参阅 错误处理。

---

另请参阅：Web 搜索视频搜索 | | 新闻搜索图像搜索 | | MCP