一、功能描述
支持用一张待检测的人脸图片，从数据集中检索最相似的前 N 张人脸图片。
二、授权说明
通过子账号使用时，需要在 授权策略 的 action 中添加 ci:DatasetFaceSearch 权限。数据万象支持的所有操作接口请参见 CI action。
三、服务开通
首次使用该功能时将默认为你开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
注意：数据万象绑定后，如果你手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。
四、使用限制
·使用检索前需要先完成 创建数据集。
·仅支持北京、上海、成都地域，即请求 Host 中<Region>仅支持填写为 ap-beijing，ap-shanghai，ap-chengdu。
·更多使用限制，详情请参见 使用限制。
五、费用说明
有关人脸比对的费用，请参见 智能检索费用。
六、请求示例
POST /datasetquery/facesearch HTTP/1.1Host: <AppId>.ci.<Region>.myqcloud.comAuthorization: Auth StringContent-Length: xxxContent-Type: application/jsonAccept: application/json
注意：说明：
注意：Authorization: Auth String，详情请参见 请求签名 文档。
七、请求头
此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。
八、请求体
{ "DatasetName": "test", "URI": "cos://examplebucket-1250000000/test.jpg", "MaxFaceNum": 1, "Limit": 10, "MatchThreshold": 10}
九、请求参数
| 参数名称 | 描述 | 类型 | 是否必选 |
| DatasetName | 数据集名称，同一个账户下唯一。该场景下仅支持选择绑定人脸检索模板的数据集。可通过 控制台 或 接口 查询。 | String | 是 |
| URI | 资源标识字段，表示需要建立索引的文件地址。 | String | 是 |
| MaxFaceNum | 输入图片中检索的人脸数量，默认值为1(传0或不传采用默认值)，最大值为10。 | Integer | 否 |
| Limit | 检索的每张人脸返回相关人脸数量，默认值为10，最大值为100。 | Integer | 否 |
| MatchThreshold | 限制返回人脸的最低相关度分数，只有超过 MatchThreshold 值的人脸才会返回。默认值为0，推荐值为80。 例如：设置 MatchThreshold 的值为80，则检索结果中仅会返回相关度分数大于等于80分的人脸。 |
Integer | 否 |
十、响应头
此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。
十一、响应体
{ "FaceResult": [{ "FaceInfos": [{ "PersonId": "xxxxx", "FaceBoundary": { "Height": 264, "Width": 203, "Left": 353, "Top": 90 }, "FaceId": "80c10056-1d40-418b-9f4f-dabf8e8cc349", "Score": 76, "URI": "cos://facesearch-1258726280/huge_hezao.webp" }], "InputFaceBoundary": { "Height": 545, "Width": 401, "Left": 737, "Top": 191 } }], "RequestId": "NjYxNTMyY2JfNGQ2ODk0MGJfNzAzZl81"}
响应包体具体数据内容如下：
| 参数名称 | 类型 | 描述 |
| FaceResult | Container Array | 人脸检索识别结果信息列表。 |
| RequestId | String | 请求 ID。 |
FaceResult 节点内容：
| 参数名称 | 类型 | 描述 |
| FaceInfos | Container Array | 相关人脸信息列表。 |
| InputFaceBoundary | Container | 输入图片的人脸框位置。 |
FaceInfos 节点内容：
| 参数名称 | 类型 | 描述 |
| PersonId | String | 自定义人物 ID。 |
| FaceBoundary | Container | 相关人脸框位置。 |
| FaceId | String | 人脸 ID。 |
| Score | Integer | 相关人脸匹配得分。 |
| URI | String | 资源标识字段，表示需要建立索引的文件地址。 |
FaceBoundary 节点内容：
| 参数名称 | 类型 | 描述 |
| Height | Integer | 人脸高度。 |
| Width | Integer | 人脸宽度。 |
| Left | Integer | 人脸框左上角横坐标。 |
| Top | Integer | 人脸框左上角纵坐标。 |
InputFaceBoundary 节点内容：
| 参数名称 | 类型 | 描述 |
| Height | Integer | 人脸高度。 |
| Width | Integer | 人脸宽度。 |
| Left | Integer | 人脸框左上角横坐标。 |
| Top | Integer | 人脸框左上角纵坐标。 |
十二、请求：进行文档检索搭配标量过滤
POST /datasetquery/facesearch 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": "test", "URI": "cos://examplebucket-1250000000/test.jpg", "MaxFaceNum": 1, "Limit": 10, "MatchThreshold": 10}
十三、响应
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={ "FaceResult": [{ "FaceInfos": [{ "PersonId": "xxxxx", "FaceBoundary": { "Height": 264, "Width": 203, "Left": 353, "Top": 90 }, "FaceId": "80c10056-1d40-418b-9f4f-dabf8e8cc349", "Score": 76, "URI": "cos://facesearch-1258726280/huge_hezao.webp" }], "InputFaceBoundary": { "Height": 545, "Width": 401, "Left": 737, "Top": 191 } }], "RequestId": "NjYxNTMyY2JfNGQ2ODk0MGJfNzAzZl81"}
十四、错误码
该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。