自动 REST API 参考

Note

从 2026 年 11 月 17 日开始,自动和自动高级版已正式提供给每个 Web IQ AppID。 没有完整文档访问权限的 AppID 获取段落。

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

所有请求都需要 API 密钥或Microsoft Entra ID访问令牌。 有关设置说明,请参阅 “身份验证 ”。

示例请求

curl -X POST "https://api.microsoft.ai/v3/auto" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "Microsoft AI announcements",
    "language": "en",
    "region": "US",
    "location": "lat:47.6062;long:-122.3321",
    "mode": "lite",
    "maxResponseLength": 30000,
    "maxCitations": 10,
    "responseFilter": ["web", "news"]
  }'

作用域内请求示例

若要使用命名范围在自动中筛选 Web 和新闻检索(请参阅范围筛选结果),包括scopeName:failOnMissingScope

curl -X POST "https://api.microsoft.ai/v3/auto" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "product setup guide",
    "scopeName": "ProductDocs",
    "failOnMissingScope": true,
    "mode": "lite",
    "responseFilter": ["web", "news"]
  }'

Parameters

参数 Required 类型 Default Description
query 是 字符串 - 搜索查询,从 1 到 1,000 个字符。
language 否 字符串 en 双字母 ISO 639-1 界面语言。
region 否 字符串 US 双字母市场或国家/地区代码。
mode 否 字符串 lite lite 确定速度的优先级; advanced 优先于全面性。
maxResponseLength 否 整数 30000 Web 结果的最大内容长度,而不是总响应长度。 低于 1500 的值被固定到 1500;超过 500000 的值被固定到 500000。 对于没有完全文档访问权限的 AppID,最大值为 30000。
maxCitations 否 整数 10 要请求的最大 Web 引文数,从 1 到 50。 低于 1 的值被固定为 1;高于 50 的值上限为 50。
location 否 字符串 - 地理上下文 lat:<latitude>;long:<longitude> 的格式,例如 lat:47.6062;long:-122.3321。
responseFilter 否 字符串数组 - 符合条件的答案类型:web、、news、timezoneweather、imagesvideos。
includeSites 否 字符串数组 - 将符合条件的 Web 结果限制为这些网站(具有可选路径的域),最多包含 250 个条目。 不会筛选新闻和其他答案类型。 使列表保持简短且与最佳结果相关。 路径最多支持两个段;更深层的路径将被截断,因此 example.com/a/b/c 被视为 example.com/a/b。
excludeSites 否 字符串数组 - 省略这些网站(具有可选路径的域)的 Web 结果,最多包含 250 个条目和与相同的路径规则 includeSites。 如果网站出现在这两个列表中,则会将其排除。 不会筛选新闻和其他答案类型。
scopeName 否 字符串 - 分配给所选 Web IQ AppID 计费帐户的集合中的一个命名范围。 使用不带空格的 1-128 ASCII 字母、 .数字、数字 _或 -空格。 对于“自动”,范围仅限制 Web 和新闻结果。 其他答案类型不会按范围进行筛选,并且可能包含其外部的结果,即使 scopeApplied 是 true。 省略或 null 表示未请求任何命名范围。 请参阅“使用范围筛选结果”。
failOnMissingScope 否 boolean true 控制回退; scopeName省略或 null 表示 true。 如果服务报告无法应用范围, true 则返回 HTTP 400 (HandlerInvalidInput)确认缺失范围,或返回 HTTP 500 (ScopeFailedToApply)其他范围故障。 false 允许在没有作用域的情况下进行搜索,并 scopeApplied: false 报告该结果时。 使用任一值应用有效的范围;零匹配结果不是范围失败。 在没有命名作用域的情况下不起作用。 请参阅 命名范围错误。

响应

成功的证据响应返回 200 OK。 每个结果都包含一个类型化的证据对象和支持它的引文。 不受支持的或格式不正确的证据与引文一起省略。 如果省略每个提供的证据结果, results 则为空。

AutoEvidenceResponse

领域 类型 Description
results AutoEvidenceResult 数组 与引文配对的证据项的范围限定为该结果。
querySignals QuerySignals 搜索查询的查询级别排名信号。
scopeApplied 布尔值 (可选) true 表示已应用请求的范围,不一定应用其最新定义。 false 表示未应用范围; failOnMissingScope: false 允许此无作用域响应。 服务不报告应用程序结果时省略。 如果没有 scopeName,则不请求命名范围;请勿假定字段存在或始终 false存在。 描述当前请求,而不是全局传播。
traceId 字符串 用于调试和支持的相关 ID。

QuerySignals

领域 类型 Description
freshness boolean 指示是否应将新文档优先于此查询的其他文档。

AutoEvidenceResult

领域 类型 Description
evidence AutoEvidence 生成的类型化证据。
citations AutoEvidenceCitation 数组 仅支持此证据结果的引文。

AutoEvidence

证据对象自己的 type 歧视性选择架构 content。 使用 证据类型索引 查找相应的定义。

领域 类型 Description
type 字符串 识别证据架构的歧视性。 值区分大小写,例如 structured/timeZone。
content 字符串或对象 形状所依赖 type的文本或结构化内容。

AutoEvidenceCitation

引文字段因答案类型和可用的源元数据而异。 并非每个引文中都存在每个字段。

领域 类型 Description
contentSource 字符串 引文源。
source 字符串 引用的网站的名称。
siteIcon 字符串 引用网站的图标 URL。
title 字符串 引文标题。
url 字符串 引文 URL。
publishedBy 字符串 引用内容的Publisher。
hostPageUrl 字符串 承载引用内容的页面的 URL。
lastUpdatedAt 字符串 上次更新时间时间戳。
crawledAt 字符串 爬网时间戳。
language 字符串 内容语言。
isAdult boolean 引文是否包含成人内容。 在将省略的字段视为false时true显式返回 。

特定于答案的引文还可以包括以下元数据:

领域 类型 适用对象 Description
observedAt 字符串 Weather 引文源提供的观察时间戳。

示例响应

{
  "results": [
    {
      "evidence": {
        "type": "text",
        "content": "Microsoft announced a new set of AI capabilities."
      },
      "citations": [
        {
          "contentSource": "web",
          "url": "https://www.microsoft.com/en-us/ai",
          "title": "Microsoft AI",
          "language": "en"
        }
      ]
    }
  ],
  "querySignals": { "freshness": true },
  "traceId": "00000000000000000000000000000000"
}

在此示例中, isAdult 省略了它,因此客户端应将其视为 false。

证据类型

使用此索引查找证据对象的 content 架构。 请求 responseFilter 中的答案类别与响应中的证据鉴别器不同:例如, timezone 请求时区答案,而返回的证据类型为 structured/timeZone。

答案类别 证据 type 内容定义
web text 文本证据:字符串内容。
news text/news 文本证据:具有可选缩略图的字符串内容。
images media/image 图像证据:图像尺寸、标题和缩略图。
videos media/video 视频证据:播放元数据、缩略图和可选时刻。
weather structured/weather 天气对象:条件、预测、警报和阳光数据。
timezone structured/timeZone 时区对象:本地时间、UTC 偏移量和比较。

下面的定义描述了公共字段。 字段在不可用时可以省略;省略的字段并不表示零度量或空答案。 源元数据和归属属于封闭结果的 引文,而不是每个定义中的重复响应信封。

示例包括说明 evidence 片段,而不是完整的响应。 请参阅封闭results和citations结构的示例响应。

文本证据

对于 text (Web) 和 text/news (News), content 是一个字符串而不是一个对象。 新闻证据也可以包括一 thumbnail 起 content。

领域 类型 Description
content 字符串 结果的文本证据。
thumbnail 对象(可选) 包含 url (字符串)、 width (整数)和 height (整数)的新闻缩略图。 维度以像素为单位。
{
  "type": "text/news",
  "content": "An example news summary.",
  "thumbnail": {
    "url": "https://example.com/news-thumbnail.jpg",
    "width": 320,
    "height": 180
  }
}

图像证据

对于 media/image, content 是一个图像对象。 源图像 URL、宿主页面 URL、标题和源日期在结果引文中提供(如果可用)。

内容字段 类型 Description
caption 字符串 生成的映像说明。
width 整数 图像宽度(以像素为单位)。
height 整数 图像高度(以像素为单位)。
thumbnailUrl 字符串 缩略图 URL。
lastUpdatedAt 字符串 当可用时,源日期采用 ISO 8601 格式。
{
  "type": "media/image",
  "content": {
    "caption": "An example city skyline.",
    "width": 1920,
    "height": 1080,
    "thumbnailUrl": "https://example.com/skyline-thumbnail.jpg"
  }
}

视频证据

对于 media/video, content 是一个视频对象。 源详细信息(如视频标题、URL、发布者和源日期)在结果引文中提供(如果可用)。

内容字段 类型 Description
description 字符串 视频内容的说明。
summary 字符串 视频的简短摘要或突出显示。
viewCount 整数 视频视图数。
length 字符串 采用格式的视频持续时间 HH:MM:SS 。
allowHttpsEmbedding boolean 是否允许 HTTPS 嵌入。
allowMobileEmbedding boolean 是否允许移动嵌入。
embeddingUrl 字符串 用于嵌入视频的 URL。
thumbnailUrl 字符串 视频缩略图 URL。
width 整数 视频宽度(以像素为单位)。
height 整数 视频高度(以像素为单位)。
lastUpdatedAt 字符串 当可用时,源日期采用 ISO 8601 格式。
bestMomentIndex 整数 最佳时刻或突出显示的索引(如果可用)。
moments VideoMoment 数组 视频段(如果可用)。 数组可以为空。
{
  "type": "media/video",
  "content": {
    "viewCount": 1200,
    "length": "00:02:30",
    "thumbnailUrl": "https://example.com/video-thumbnail.jpg",
    "moments": []
  }
}

VideoMoment

领域 类型 Description
title 字符串 段标题。
description 字符串 段的说明。
startTime 字符串 以格式分段开始时间 d.hh:mm:ss 。
endTime 字符串 以格式分段结束时间 d.hh:mm:ss 。
momentUrl 字符串 直接指向段的 URL。

Weather 对象

当查询与天气有关时,自动可以返回每个位置的一个 structured/weather 结果。 字段包含在可用时。 一 units起读取数值度量;不假定固定单位系统。

内容字段 类型 Description
location 字符串 位置名称,例如 Seattle, Washington。
url 字符串 位置的天气属性 URL。 同一 URL 位于结果的引文中。
units 对象 单位系统(system)和单位,用于temperature、speed、pressuredistance、、height和time。
alerts WeatherAlert 数组 按用户所在国家或地区筛选的位置的活动或最近的天气警报。
currentWeather 对象 当前条件,包括condition、dayPeriod、、、universalThermalClimateIndexfeelsLikehumiditydewPointuvvisibilitytemperaturepressureuvLevel、windSpeed、、windDirection、、windGust以及airQualityobservedAt可用时间。
forecastedWeather 对象数组 每日预报,包括validDate、condition、、temperatureHigh、feelsLikeLowfeelsLikeHightemperatureLowprecipitationChance、雨雪量、humidityday、nightalmanac、和hourly预测(如果可用)。
sunlight 对象 当查询要求特定日期时,日出、日落、月亮、月亮和月相。

当前airQuality可以包含index、severity和 primaryPollutantvalidAt。 每日预测 humidity 可以包含 high 和 low。 其day和night子预测可以包含condition、precipitationChance和windSpeedwindDirection。 它 almanac 包含的 validDate太阳和月亮数据。

{
  "type": "structured/weather",
  "content": {
    "location": "Seattle, Washington",
    "units": {
      "system": "Imperial",
      "temperature": "F"
    },
    "currentWeather": {
      "condition": "Cloudy",
      "temperature": 50
    }
  }
}

WeatherAlert

领域 类型 Description
id 字符串 提供程序提供的警报标识符(如果可用)。
name 字符串 天气事件名称,例如 Frost。
severity 字符串 严重性,例如 Advisory, Watch或 Warning。
status 字符串 例如 Ongoing,警报状态。
issuingAuthority 字符串 发出警报的组织,例如 National Weather Service。
url 字符串 链接到颁发机构。 源提供它时包含。
description 字符串 危险描述和受影响区域。
safetyGuidance 字符串 建议的安全操作(如果可用)。
issuedAt、effectiveAt、expiresAt 字符串 发出警报后,生效并过期。

时区对象

对于 structured/timeZone, content 描述本地时间或比较两个时区。 位置查找可以返回 timeZones;比较可以改为返回 startTimeZone, endTimeZone并且 timeDifference。 不需要每个答案中的所有字段。

内容字段 类型 Description
description 字符串 人工可读答案摘要(如果可用)。
timeZones TimeZoneEntry 数组 单位置或多位置时间应答的条目。
startTimeZone TimeZoneEntry 比较的源时区。
endTimeZone TimeZoneEntry 比较的目标时区。
timeDifference 字符串 用于比较的人类可读时间差异说明。
{
  "type": "structured/timeZone",
  "content": {
    "timeZones": [
      {
        "timeZoneName": "Pacific Standard Time",
        "timeZoneAbbreviation": "PST",
        "location": "Seattle, Washington",
        "utcOffset": -8,
        "utcTime": "Monday, 2026-11-16T05:00:00Z",
        "localTime": "Sunday, 2026-11-15T21:00:00-08:00"
      }
    ]
  }
}

TimeZoneEntry

领域 类型 Description
timeZoneName 字符串 完整时区名称。
timeZoneAbbreviation 字符串 缩写,例如 PST 或 IST。
location 字符串 与条目关联的城市、国家或地区。
utcOffset number UTC 偏移量(以小时为单位)。 例如,可以是小数部分,也可以在 5.5不可用时省略。
utcTime 字符串 UTC 时间作为格式化字符串。
localTime 字符串 本地时间作为格式化字符串。

时间字符串可以包含星期几前缀;不要假设它们是裸露的 ISO 8601 时间戳。

错误代码

状态代码 Description
200 请求成功,包括没有结果的有效搜索。
400 无效的参数或格式不正确的 JSON。
401 缺少或无效的身份验证凭据。
403 未为自动启用经过身份验证的 Web IQ AppID。
429 超出速率或配额限制。
500 内部服务失败。
503 所需的服务不可用。
504 请求超时。

有关共享错误架构和重试指南,请参阅 错误处理。