通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

视频检索 API 参考

重要

2025 年 6 月 30 日，Azure AI 视觉视频检索将停用。 停用此功能的决定是我们不断改进和简化和改进为视频处理提供的功能的一部分。 迁移到 Azure AI 内容理解和 Azure AI 搜索，从其附加功能中受益。

视频处理：视频检索与 Azure AI 内容理解

功能 / 特点 用于视频描述的视频检索 Azure AI 内容解析
支持的视频长度 针对短视频进行优化，最多 3 分钟 支持短视频和长视频，最多 4 小时
帧处理 最多 20 帧 批处理，对整个视频逐帧进行采样。
内容提取预处理 转录 听录、镜头识别、人脸分组
结构化输出支持 不支持 支持符合架构的结构化输出
数据类型 支持的视频 支持的视频、图像、文档和语音
定价 基于令牌的变量 已处理视频每分钟固定成本

若要迁移到视频摘要和说明的内容理解，建议查看 Azure AI 内容理解文档。

视频搜索：视频检索与 Azure AI 搜索和内容理解

功能 / 特点 用于视频搜索的视频检索 Azure AI 搜索和内容理解
视觉嵌入类型 基于帧的图像嵌入 视频描述文本嵌入
内容提取预处理 转录，OCR 听录、镜头识别、人脸分组
人员与对象搜索支持 大力支持 大力支持
行动和事件支持 受限制 大力支持
自定义 没有 可以通过使用字段和字段说明来定制内容理解分析器，以便更好地聚焦

若要开始使用内容理解构建搜索用例，建议从 此示例 开始，此示例演示如何使用 Azure AI 搜索来搜索视频。

为了避免服务中断，请在 2025 年 6 月 30 日前迁移。

身份验证

调用本文档中的任何 API 时，请包含以下标头。

Ocp-Apim-Subscription-Key：版本： YOUR_COMPUTER_VISION_KEY2023-05-01-preview

CreateIndex

网址

PUT /retrieval/indexes/{indexName}?api-version=<version_number>

说明

此方法会创建索引，然后索引可用于引入文档。 需要先创建索引，然后才能执行引入。

参数

名称 所在位置 说明 必需 类型
indexName 路径 要创建的索引的名称。 是 字符串
API版本 (api-version) 查询 请求的 API 版本。 是 字符串
身体 身体 包含可用于搜索的元数据的请求正文。 是 CreateIngestionIndexRequestModel

响应

代码 说明 类型
201 已创建 GetIngestionIndexResponseModel

GetIndex

网址

GET /retrieval/indexes/{indexName}?api-version=<version_number>

说明

检索具有指定名称的索引。

参数

名称 所在位置 说明 必需 类型
indexName 路径 要检索的索引的名称。 是 字符串
API版本 (api-version) 查询 请求的 API 版本。 是 字符串

响应

代码 说明 类型
200 成功 GetIngestionIndexResponseModel
默认值 错误 ErrorResponse

UpdateIndex

网址

PATCH /retrieval/indexes/{indexName}?api-version=<version_number>

说明

更新具有指定名称的索引。

参数

名称 所在位置 说明 必需 类型
indexName 路径 要更新的索引的名称。 是 字符串
API版本 (api-version) 查询 请求的 API 版本。 是 字符串
身体 身体 包含要应用于索引的更新的请求正文。 是 UpdateIngestionIndexRequestModel

响应

代码 说明 类型
200 成功 GetIngestionIndexResponseModel
默认值 错误 ErrorResponse

DeleteIndex

网址

DELETE /retrieval/indexes/{indexName}?api-version=<version_number>

说明

删除索引及其所有关联的引入文档。

参数

名称 所在位置 说明 必需 类型
indexName 路径 要删除的索引的名称。 是 字符串
API版本 (api-version) 查询 请求的 API 版本。 是 字符串

响应

代码 说明
204 无内容

ListIndexes

网址

GET /retrieval/indexes?api-version=<version_number>

说明

检索所有引入的所有索引的列表。

参数

名称 所在位置 说明 必需 类型
$skip 查询 要跳过的数据集数。 否 整数
$top 查询 跳过后要返回的数据集数。 否 整数
API版本 (api-version) 查询 请求的 API 版本。 是 字符串

响应

代码 说明 类型
200 成功 GetIngestionIndexResponseModelCollectionApiModel
默认值 错误 ErrorResponse

CreateIngestion

网址

PUT /retrieval/indexes/{indexName}/ingestions/{ingestionName}?api-version=<version_number>

说明

引入请求可以具有视频有效负载。 它可以具有三种模式之一（添加、更新或删除）。 添加模式将创建引入并处理视频。 更新模式将仅更新元数据。 为了重新处理视频，需要删除引入并重新创建它。

参数

名称 所在位置 说明 必需 类型
indexName 路径 要向其创建引入的索引的名称。 是 字符串
ingestionName 路径 要创建的引入的名称。 是 字符串
API版本 (api-version) 查询 请求的 API 版本。 是 字符串
身体 身体 包含要创建的引入请求的请求正文。 是 CreateIngestionRequestModel

响应

代码 说明 类型
202 已接受 IngestionResponseModel

GetIngestion

网址

GET /retrieval/indexes/{indexName}/ingestions/{ingestionName}?api-version=<version_number>

说明

获取指定索引和引入名称的引入状态。

参数

名称 所在位置 说明 必需 类型
indexName 路径 要为其检查引入状态的索引的名称。 是 字符串
ingestionName 路径 要检索的引入的名称。 是 字符串
detailLevel 查询 用于指示每个文档引入状态的详细程度的级别。 否 字符串
API版本 (api-version) 查询 请求的 API 版本。 是 字符串

响应

代码 说明 类型
200 成功 IngestionResponseModel
默认值 错误 ErrorResponse

ListIngestions

网址

GET /retrieval/indexes/{indexName}/ingestions?api-version=<version_number>

说明

检索特定索引的所有引入。

参数

名称 所在位置 说明 必需 类型
indexName 路径 要为其检索引入的索引的名称。 是 字符串
API版本 (api-version) 查询 请求的 API 版本。 是 字符串

响应

代码 说明 类型
200 成功 IngestionResponseModelCollectionApiModel
默认值 错误 ErrorResponse

ListDocuments

网址

GET /retrieval/indexes/{indexName}/documents?api-version=<version_number>

说明

检索特定索引的所有文档。

参数

名称 所在位置 说明 必需 类型
indexName 路径 要为其检索文档的索引的名称。 是 字符串
$skip 查询 要跳过的数据集数。 否 整数
$top 查询 跳过后要返回的数据集数。 否 整数
API版本 (api-version) 查询 请求的 API 版本。 是 字符串

响应

代码 说明 类型
200 成功 IngestionDocumentResponseModelCollectionApiModel
默认值 错误 ErrorResponse

SearchByText

网址

POST /retrieval/indexes/{indexName}:queryByText?api-version=<version_number>

说明

对指定的索引执行基于文本的搜索。

参数

名称 所在位置 说明 必需 类型
indexName 路径 要搜索的索引的名称。 是 字符串
API版本 (api-version) 查询 请求的 API 版本。 是 字符串
身体 身体 包含查询和其他参数的请求正文。 是 SearchQueryTextRequestModel

响应

代码 说明 类型
200 成功 SearchResultDocumentModelCollectionApiModel
默认值 错误 ErrorResponse

模型

CreateIngestionIndexRequestModel

表示 JSON 文档的创建引入索引请求模型。

名称 类型 说明 必需
metadataSchema MetadataSchemaModel 否
功能 [ FeatureModel ] 获取或设置文档的特征列表。 默认值为“vision”。 否
userData 物体 获取或设置文档的用户数据。 否

CreateIngestionRequestModel

表示 JSON 文档的创建引入请求模型。

名称 类型 说明 必需
视频 [ IngestionDocumentRequestModel ] 获取或设置 JSON 文档中的视频文档引入请求的列表。 否
审查 布尔 获取或设置审查标志，指示是否应审查内容。 否
generateInsightIntervals 布尔 获取或设置间隔生成标志，指示是否应生成见解间隔。 否
documentAuthenticationKind 字符串 获取或设置用于下载文档的身份验证类型。
枚举："none"、"managedIdentity"		 否
filterDefectedFrames 布尔 将评估用于指示帧的帧筛选器标志，并筛选掉所有缺陷（例如模糊、低光、过度曝光）帧。 否
includeSpeechTranscript 布尔 获取或设置脚本生成标志，指示是否应生成脚本。 否

DatetimeFilterModel

表示要应用于搜索查询的日期/时间筛选器。

名称 类型 说明 必需
fieldName 字符串 获取或设置要对其进行筛选的字段的名称。 是
开始时间 字符串 获取或设置要对其进行筛选的范围的开始时间。 否
endTime 字符串 获取或设置要对其进行筛选的范围的结束时间。 否

错误响应

发生错误时返回的响应。

名称 类型 说明 必需
错误 ErrorResponseDetails 是

ErrorResponseDetails

错误信息。

名称 类型 说明 必需
代码 字符串 错误代码。 是
消息 字符串 错误消息。 是
目标 字符串 错误的目标。 否
详细信息 [ ErrorResponseDetails ] 详细错误的列表。 否
innererror ErrorResponseInnerError 否

ErrorResponseInnerError

详细错误。

名称 类型 说明 必需
代码 字符串 错误代码。 是
消息 字符串 错误消息。 是
innererror ErrorResponseInnerError 否

FeatureModel

表示索引中的特征。

名称 类型 说明 必需
姓名 字符串 获取或设置特征的名称。
枚举："vision"、"speech"		 是
modelVersion 字符串 获取或设置特征的模型版本。 否
域 字符串 获取或设置特征的模型域。
枚举："generic"、"surveillance"		 否

GetIngestionIndexResponseModel

表示 JSON 文档的获取引入索引响应模型。

名称 类型 说明 必需
姓名 字符串 获取或设置索引名称属性。 否
metadataSchema MetadataSchemaModel 否
userData 物体 获取或设置文档的用户数据。 否
功能 [ FeatureModel ] 获取或设置索引中的特征的列表。 否
eTag 字符串 获取或设置 etag。 是
createdDateTime dateTime 获取或设置创建日期和时间属性。 是
lastModifiedDateTime dateTime 获取或设置上次修改日期和时间属性。 是

GetIngestionIndexResponseModelCollectionApiModel

包含可能分页的结果数组。

名称 类型 说明 必需
价值 [ GetIngestionIndexResponseModel ] 结果数组。 是
nextLink 字符串 如果有更多结果可用，则是指向下一组分页结果的链接；否则不存在。 否

IngestionDocumentRequestModel

表示 JSON 文档中的视频文档引入请求。

名称 类型 说明 必需
模式 字符串 获取或设置文档的引入模式。
枚举："add"、"update"、"remove"		 是
documentId 字符串 获取或设置文档 ID。 否
documentUrl 字符串 (uri) 获取或设置文档 URL。 共享访问签名 (SAS)，如果有，将从 URL 中删除。 是
元数据 物体 获取或设置文档的元数据作为名称/值对的字典。 否
userData 物体 获取或设置文档的用户数据。 否

IngestionDocumentResponseModel

表示 JSON 文档中的引入文档响应对象。

名称 类型 说明 必需
documentId 字符串 获取或设置文档 ID。 否
documentUrl 字符串 (uri) 获取或设置文档 URL。 共享访问签名 (SAS)，如果有，将从 URL 中删除。 否
元数据 物体 获取或设置元数据的键值对。 否
错误 ErrorResponseDetails 否
createdDateTime dateTime 获取或设置文档的创建日期和时间。 否
lastModifiedDateTime dateTime 获取或设置文档的上次修改日期和时间。 否
userData 物体 获取或设置文档的用户数据。 否

IngestionDocumentResponseModelCollectionApiModel

包含可能分页的结果数组。

名称 类型 说明 必需
价值 [ IngestionDocumentResponseModel ] 结果数组。 是
nextLink 字符串 如果有更多结果可用，则是指向下一组分页结果的链接；否则不存在。 否

IngestionErrorDetailsApiModel

表示每个文档的引入错误信息。

名称 类型 说明 必需
代码 字符串 错误代码。 否
消息 字符串 错误消息。 否
innerError IngestionInnerErrorDetailsApiModel 否

IngestionInnerErrorDetailsApiModel

表示每个文档的引入内部错误信息。

名称 类型 说明 必需
代码 字符串 错误代码。 否
消息 字符串 错误消息。 否
innerError IngestionInnerErrorDetailsApiModel 否

IngestionResponseModel

表示 JSON 文档的引入响应模型。

名称 类型 说明 必需
姓名 字符串 获取或设置引入的名称。 否
State 字符串 获取或设置引入的状态。
枚举："notStarted"、"running"、"completed"、"failed"、"partiallySucceeded"		 否
错误 ErrorResponseDetails 否
batchName 字符串 与此引入关联的批的名称。 否
createdDateTime dateTime 获取或设置引入的创建日期和时间。 否
lastModifiedDateTime dateTime 获取或设置引入的上次修改日期和时间。 否
fileStatusDetails [ IngestionStatusDetailsApiModel ] 每个文档的引入状态的列表。 否

IngestionResponseModelCollectionApiModel

包含可能分页的结果数组。

名称 类型 说明 必需
价值 [ IngestionResponseModel ] 结果数组。 是
nextLink 字符串 如果有更多结果可用，则是指向下一组分页结果的链接；否则不存在。 否

IngestionStatusDetailsApiModel

表示每个文档的引入状态详细信息。

名称 类型 说明 必需
最后更新时间 dateTime 批区块的状态更新时间。 是
documentId 字符串 文档 ID。 是
documentUrl 字符串 (uri) 文档的 URL。 否
成功 布尔 用于指示推理是否成功的标志。 是
错误 IngestionErrorDetailsApiModel 否

MetadataSchemaFieldModel

表示元数据架构中的字段。

名称 类型 说明 必需
姓名 字符串 获取或设置字段的名称。 是
搜索 布尔 获取或设置一个值，该值指示字段是否可搜索。 是
filterable 布尔 获取或设置一个值，该值指示字段是否可筛选。 是
类型 字符串 获取或设置字段的类型。 可以是字符串或日期/时间。
枚举："string"、"datetime"		 是

MetadataSchemaModel

表示文档的元数据架构。

名称 类型 说明 必需
语言 字符串 获取或设置元数据架构的语言。 默认值为“en”。 否
字段 [ MetadataSchemaFieldModel ] 获取或设置元数据架构中字段的列表。 是

SearchFiltersModel

表示要应用于搜索查询的筛选器。

名称 类型 说明 必需
stringFilters [ StringFilterModel ] 获取或设置要应用于搜索查询的字符串筛选器。 否
datetimeFilters [ DatetimeFilterModel ] 获取或设置要应用于搜索查询的日期/时间筛选器。 否
featureFilters [ string ] 获取或设置要应用于搜索查询的特征筛选器。 否

SearchQueryTextRequestModel

表示用于基于文本的搜索的搜索查询请求模型。

名称 类型 说明 必需
queryText 字符串 获取或设置查询文本。 是
筛选器 SearchFiltersModel 否
审查 布尔 获取或设置一个布尔值，该值指示审查是处于启用还是禁用状态。 否
顶部 整数 获取或设置要检索的结果数。 是
跳过 整数 获取或设置要跳过的结果数。 是
additionalIndexNames [ string ] 获取或设置要包含在搜索查询中的其他索引名称。 否
dedup 布尔 是否删除类似的视频帧。 是
dedupMaxDocumentCount 整数 重复数据删除后的文档数上限。 是
disableMetadataSearch 布尔 获取或设置一个布尔值，该值指示是否在搜索中禁用元数据。 是

SearchResultDocumentModel

表示搜索查询响应。

名称 类型 说明 必需
documentId 字符串 获取或设置文档的 ID。 否
documentKind 字符串 获取或设置文档的种类，可以是“视频”。 否
开始 字符串 获取或设置文档的开始时间。 此属性仅适用于视频文档。 否
结束 字符串 获取或设置文档的结束时间。 此属性仅适用于视频文档。 否
最好 字符串 获取或设置相关性分数最高的文档的时间戳。 此属性仅适用于视频文档。 否
相关性 翻倍 获取或设置文档的相关性分数。 是
additionalMetadata 物体 获取或设置与搜索相关的其他元数据。 否

SearchResultDocumentModelCollectionApiModel

包含可能分页的结果数组。

名称 类型 说明 必需
价值 [ SearchResultDocumentModel ] 结果数组。 是
nextLink 字符串 如果有更多结果可用，则是指向下一组分页结果的链接；否则不存在。 否

StringFilterModel

表示要应用于搜索查询的字符串筛选器。

名称 类型 说明 必需
fieldName 字符串 获取或设置要对其进行筛选的字段的名称。 是
值 [ string ] 获取或设置要对其进行筛选的值。 是

UpdateIngestionIndexRequestModel

表示 JSON 文档的更新引入索引请求模型。

名称 类型 说明 必需
metadataSchema MetadataSchemaModel 否
userData 物体 获取或设置文档的用户数据。 否