一、功能描述
·对数据集内的视频文件进行视频检索。支持输入自然语言文本，在指定数据集中检索出与输入文本语义相似的视频片段，并返回片段所属视频的 COS 地址以及片段的起止时间点，实现以文搜视频片段。
·除场景、动作、物体等自然语言描述外，视频检索还支持直接输入人名进行检索，检索出与该人物相关的视频片段（该能力依赖视频入库时提取的语音识别、字幕识别、人脸信息等 AI 元数据）。
·混合检索-视频检索支持使用标量过滤能力，支持的字段和操作符请参见 标量过滤字段与操作符支持列表。
注意：说明：
三、服务开通
首次使用该功能时将默认为你开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
四、使用限制
·使用检索前需要先完成 创建数据集，并选择 Official:VideoSearch 模板完成视频入库。
·仅支持北京、上海、成都地域，即请求 Host 中 <Region> 仅支持填写为 ap-beijing，ap-shanghai，ap-chengdu。
·视频检索仅支持 text（自然语言检索）模式，Mode 必须为 text；若在 VideoSearch 模板下传入 Mode=pic，接口将返回 Param Mode must be text for VideoSearch. 错误。
·检索语句 SearchText 最多支持60个 UTF-8 编码字符。
·更多使用限制，详情请参见 使用限制。
五、费用说明
有关混合检索-视频检索的费用，请参见 智能检索费用。
七、请求示例
POST /datasetquery/hybridsearch HTTP/1.1Host: <AppId>.ci.<Region>.myqcloud.comAuthorization: Auth StringContent-Length: xxxContent-Type: application/jsonAccept: application/json
注意：说明：
注意：Authorization: Auth String，详情请参见 请求签名 文档。
八、请求头
此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。
九、请求体
请求体示例一：以文搜视频片段（场景/动作描述）
{ "DatasetName": "videosearch", "Mode": "text", "Templates": "VideoSearch", "SearchText": "熊猫在草地上玩耍的片段", "Limit": 10, "MatchThreshold": 0, "Filter": { "$and": [{ "MediaType": { "$in": ["image", "document", "video"] } }, { "Size": { "$gt": 123 } } ] }}
请求体示例二：以人名搜视频片段
{ "DatasetName": "videosearch", "Mode": "text", "Templates": "VideoSearch", "SearchText": "张三", "Limit": 10, "MatchThreshold": 0, "Filter": { "$and": [{ "MediaType": { "$in": ["image", "document", "video"] } }, { "Size": { "$gt": 123 } } ] }}
十、请求参数
| 参数名称 | 描述 | 类型 | 是否必选 |
| DatasetName | 数据集名称，同一个账户下唯一 | String | 是 |
| Mode | 指定检索的输入类型。视频检索时取值为：text：表示输入文本进行检索，支持输入自然语言（例如“熊猫在草地上玩耍的片段”）或知名人名（例如“张三”）视频检索仅支持 text 模式，不支持 pic 模式 | String | 是 |
| Templates | 指定输出的数据类型。视频检索时取值为：VideoSearch：进行视频检索，输出的是视频片段类型的结果（Mode 必须为 text） | String | 是 |
| SearchText | 检索语句。最多支持60个 UTF-8 编码字符。支持两类输入：自然语言描述：例如“熊猫在草地上玩耍的片段”，按场景、动作、物体等语义匹配视频片段知名人名：例如“张三”，检索出与该人物相关的视频片段 | String | 是 |
| Limit | 返回相关视频片段的数量，默认值为10，取值范围为(0, 100] | Integer | 否 |
| MatchThreshold | 限制返回视频片段的最低相关度分数，只有超过 MatchThreshold 值的片段才会返回。默认值为0，推荐值为80，取值范围为(0, 100]例如：设置 MatchThreshold 的值为80，则检索结果中仅会返回相关度分数大于等于80分的视频片段 | Integer | 否 |
| Filter | 简单查询参数条件，可选参数，可以包含三个条件。关于数据格式，请参见 字段和操作符的支持列表 | Container | 否 |
十二、响应头
此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。
十三、响应体
响应体示例：视频检索返回结果
{ "VideoResult": [{ "URI": "cos://examplebucket-1250000000/panda_play_001.mp4", "From": 8.333333, "To": 14.916667, "Score": 43 }, { "URI": "cos://examplebucket-1250000000/panda_play_002.mp4", "From": 0, "To": 8.333333, "Score": 42 }], "RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"}
响应包体具体数据内容如下：
| 参数名称 | 类型 | 描述 |
| RequestId | String | 请求 ID |
| VideoResult | Container Array | 视频检索识别结果信息列表 |
VideoResult 节点内容：
| 参数名称 | 类型 | 描述 |
| URI | String | 匹配视频在对象存储中的统一资源标识符（URI） |
| From | Float | 匹配视频片段的起始时间，单位为秒 |
| To | Float | 匹配视频片段的结束时间，单位为秒 |
| Score | Integer | 搜索结果的相关度评分，数值越高表示相关性越强 |
十五、案例一：以文搜视频片段
以下示例通过传入自然语言描述“熊猫在草地上玩耍的片段”进行视频检索，返回匹配的视频片段（含所属视频、起止时间区间与相关度评分），效果如下：
十六、请求
POST /datasetquery/hybridsearch HTTP/1.1Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=****************************************Host: 1234567890.ci.ap-beijing.myqcloud.comContent-Length: 166Content-Type: application/jsonAccept: application/json{ "DatasetName": "videosearch", "Mode": "text", "Templates": "VideoSearch", "SearchText": "熊猫在草地上玩耍的片段", "Limit": 10, "MatchThreshold": 0, "Filter": { "$and": [{ "MediaType": { "$in": ["image", "document", "video"] } }, { "Size": { "$gt": 123 } } ] }}
十七、响应
HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 230Connection: keep-aliveDate: Mon, 28 Jun 2022 15:23:12 GMTServer: tencent-cix-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc={ "VideoResult": [{ "URI": "cos://examplebucket-1250000000/panda_play_001.mp4", "From": 8.333333, "To": 14.916667, "Score": 43 }, { "URI": "cos://examplebucket-1250000000/panda_play_002.mp4", "From": 0, "To": 8.333333, "Score": 42 }], "DocResult": [], "ImageResult": [], "RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"}
十八、案例二：以人名搜视频片段
以下示例通过传入人名“张三”进行视频检索，返回与该人物相关的视频片段（含所属视频、起止时间区间与相关度评分），效果如下：
十九、请求
POST /datasetquery/hybridsearch HTTP/1.1Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=****************************************Host: 1234567890.ci.ap-beijing.myqcloud.comContent-Length: 150Content-Type: application/jsonAccept: application/json{ "DatasetName": "videosearch", "Mode": "text", "Templates": "VideoSearch", "SearchText": "张三", "Limit": 10, "MatchThreshold": 0, "Filter": { "$and": [{ "MediaType": { "$in": ["image", "document", "video"] } }, { "Size": { "$gt": 123 } } ] }}
20、响应
HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 230Connection: keep-aliveDate: Mon, 28 Jun 2022 15:23:12 GMTServer: tencent-cix-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc={ "VideoResult": [{ "URI": "cos://examplebucket-1250000000/interview_001.mp4", "From": 211.166672, "To": 215.583328, "Score": 51 }, { "URI": "cos://examplebucket-1250000000/interview_002.mp4", "From": 0, "To": 8.333333, "Score": 46 }], "DocResult": [], "ImageResult": [], "RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"}
21、错误码
该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。