视频搜索 REST API 参考

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

示例请求：

curl -X POST "https://api.microsoft.ai/v3/search/videos" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "cute puppy videos",
    "maxResults": 30,
    "language": "en",
    "region": "US"
  }'

Parameters

参数 Required 类型 Default Description
查询 是 字符串 - 搜索查询字符串。 最大长度为 1000 个字符。
maxResults 否 整数 30 要返回的最大结果数。 默认值为 30，最大值为 30。
语言 否 字符串 “en” 搜索结果中接口语言的 2 字母 ISO 639-1 语言代码。 有关完整列表，请参阅 “支持的语言 ”。
区域 否 字符串 "US" 结果应来自的 2 个字母国家/地区代码（例如“US”、“JP”、“GB”等）。 有关完整列表，请参阅 “支持的区域 ”。
enablePlaylist 否 boolean false 是否在响应中包含播放列表结果。
freshness 否 字符串 - 根据发现日期筛选结果的时间范围。 支持相对时间的“week”、“month”、“year”或 ISO 8601 日期间隔格式：“YYYY-MM-DD/YYYY-MM-DD”或“YYYY-MM-DDTHH：mm：ssZ/YYYY-MM-DDTHH：mm：ssZ”，请使用 .。 （如果省略开始日期或结束日期）。
embeddable 否 字符串数组 - 通过嵌入功能筛选视频。 允许的值：“player”（具有可嵌入的玩家）。 如果未设置，则不会应用筛选。
分辨率 否 字符串 - 按 最低 分辨率筛选视频。 值：“360p”、“480p”、“720p”、“1080p”。 如果未设置，则不会应用筛选。
safeSearch 否 字符串 “strict” 安全搜索筛选级别。 值：“off”、“strict”。 默认值为“strict”。
duration 否 字符串 - 按持续时间范围筛选视频。 值：“short”（<5 分钟）、“medium”（5-20 分钟）、“long”（>20 分钟）。 如果未设置，则不会应用筛选。

请求标头

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

响应

视频响应

领域 类型 Description
videoResults videoResult 数组 视频结果列表。
播放列表 playlistResult 数组（可选） 播放列表结果列表。
instrumentationClickBase 字符串 单击 ping 请求的基 URL。 在结果项中追加一个 instrumentationSuffix 值，以形成完整的 ping URL。 仅适用于具有 EnableInstrumentationPing 配置文件标志的应用程序。 注意：还可以使用 URL 重定向记录用户单击。 启用重定向后，无需执行任何操作即可记录用户单击，并且 instrumentationClickBase 不会包含在响应中。 有关设置说明，请参阅 检测指南 。
instrumentationCitationBase 字符串 LLM 日志 ping 请求的基 URL。 追加数据有效负载以形成完整的 ping URL。 仅适用于具有 EnableInstrumentationPing 配置文件标志的应用程序。
traceId 字符串 用于调试的跟踪 ID。

Note

playlists 是可选字段， enablePlaylist 即使设置为 true。

videoResult

领域 类型 Description
title 字符串 视频的标题或名称。
url 字符串 视频的源 URL。 对于启用了 URL 重定向的中国用户，此字段包含的重定向 URL 与 clickUrl.
域 字符串 结果的目标主机。 仅针对启用了 URL 重定向的中国用户返回。
description 字符串 视频内容的说明。 这是由视频上传程序提供，也可以由 LLM 生成。
publishedBy 字符串 视频的上传者或发布者。
viewCount long 视频具有的观看次数。
摘要 字符串 AI 生成的视频摘要。
length 字符串 HH：MM：SS 格式的视频长度。
allowHttpsEmbedding boolean 是否允许 HTTPS 嵌入。
allowMobileEmbedding boolean 是否允许移动嵌入。
embeddingUrl 字符串 用于嵌入视频的 URL。
最后更新时间 字符串 上次更新的日期作为格式化字符串。
bestMomentIndex 整数 视频中最佳时刻或突出显示的索引。
时刻 时刻数组 视频段/时刻的数组。
缩略图URL 字符串 视频的缩略图 URL。
宽度 整数 视频的宽度（以像素为单位）。
height 整数 视频的高度（以像素为单位）。
isAdult boolean 指示结果是否包括成人内容。
clickUrl 字符串 通过必应代理单击的重定向 URL。 仅当启用单击重定向时才会显示。
instrumentationSuffix 字符串 要追加到此结果项的检测 ping URL 基的后缀。 用作检测 ping URL 和重定向的 clickUrl K 值。 启用检测 ping 时存在。

Note

上述几个字段是可选的 ， 如果这些字段可用，则会提供它们。

moment

领域 类型 Description
title 字符串 时刻段的标题。
description 字符串 描述这一刻会发生什么。
startTime 字符串 时刻的开始时间，格式为“d.hh：mm：ss”。
endTime 字符串 时刻的结束时间，格式为“d.hh：mm：ss”。
momentUrl 字符串 在视频中定向到此特定时刻的 URL。

Note

moment 是可选的响应对象。 它不适用于每个视频结果。

playlistResult

领域 类型 Description
title 字符串 播放列表的标题。
description 字符串 播放列表的说明。
视频 视频数组 播放列表中的视频数组。

Note

playlistResult 是可选的响应对象。

视频

领域 类型 Description
title 字符串 视频的标题。
description 字符串 视频的说明。
url 字符串 视频的 URL。

错误代码

状态代码 错误类别 Description 常见原因
200 成功 请求成功。 -
400 错误的请求 无效的请求参数。 缺少必填字段、无效参数值、格式不正确的 JSON
401 Unauthorized 身份验证失败或缺失。 API 密钥无效，缺少 x-apikey 标头
403 禁止 有效凭据但权限不足。 API 密钥缺少所需的权限
410 不存在 (Gone) 需要 HTTPS。 通过 HTTP 而不是 HTTPS 发出的请求
415 不支持的媒体类型 不支持内容类型。 缺少或不正确的内容类型标头
429 请求过多 超出速率限制。 时间范围内请求过多
500 内部服务器错误 意外的服务器错误。 临时服务器问题
503 服务不可用 服务暂时不可用。 维护或临时中断
504 网关超时 请求已超时。 上游服务超时

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

另请参阅：Web 搜索 | 浏览 | 新闻搜索图像搜索 | | MCP

  • 上次更新时间为