数据万象人脸检索-API 文档-文档中心-腾讯云

功能描述
支持用一张待检测的人脸图片，从数据集中检索出与最相似的前 N 张人脸图片。
费用说明
有关人脸检索的费用，请参见 智能检索费用。
授权说明
授权策略中 action 设置为 ci:DatasetFaceSearch ，详情请参见 数据万象 action。
限制说明
每次检索，可识别图片中的最多 10 张人脸。
每张人脸最多可返回相关人脸数量为10，即一张人脸图片最多可返回相关人脸图片数量为100。
请求
请求示例
POST /datasetquery/facesearch HTTP/1.1
Host: <AppId>.ci.<Region>.myqcloud.com
Authorization: Auth String
Content-Length: xxx
Content-Type: application/json
Accept: 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
人脸框左上角纵坐标。

参数名称	描述	类型	是否必选
DatasetName	数据集名称，同一个账户下唯一。	String	是
URI	资源标识字段，表示需要建立索引的文件地址。	String	是
MaxFaceNum	输入图片中检索的人脸数量，默认值为1(传0或不传采用默认值)，最大值为10。	Integer	否
Limit	检索的每张人脸返回相关人脸数量，默认值为10，最大值为100。	Integer	否
MatchThreshold	限制返回人脸的最低相关度分数，只有超过 MatchThreshold 值的人脸才会返回。默认值为0，推荐值为80。例如：设置 MatchThreshold 的值为80，则检索结果中仅会返回相关度分数大于等于80分的人脸。	Integer	否

人脸检索

本页目录：

功能描述

费用说明

授权说明

限制说明

请求

请求示例

请求头

请求体

请求参数

响应

响应头

响应体