帮你快速理解、总结文档立即下载
文档中心>对象存储>向量存储与检索>人脸检索>人脸比对

人脸比对

最近更新时间：2026-07-28 18:23:03

我的收藏

本页目录：

功能描述

支持用一张待检测的人脸图片，从数据集中检索最相似的前 N 张人脸图片。


授权说明

通过子账号使用时，需要在 授权策略 的 action 中添加 ci:DatasetFaceSearch 权限。数据万象支持的所有操作接口请参见 CI action。

服务开通

首次使用该功能时将默认为您开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
注意：
数据万象绑定后，如果您手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。

使用限制

使用检索前需要先完成 创建数据集。
仅支持北京、上海、成都地域，即请求 Host 中<Region>仅支持填写为 ap-beijing，ap-shanghai，ap-chengdu。
更多使用限制，详情请参见 使用限制。

费用说明

有关人脸比对的费用，请参见 智能检索费用。

请求

请求示例

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
人脸框左上角纵坐标。

使用案例

请求：进行文档检索搭配标量过滤

POST /datasetquery/facesearch HTTP/1.1
Authorization: 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.com
Content-Length: 166
Content-Type: application/json
Accept: application/json


{
    "DatasetName": "test",
    "URI": "cos://examplebucket-1250000000/test.jpg",
    "MaxFaceNum": 1,
    "Limit": 10,
    "MatchThreshold": 10
}

响应

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 230
Connection: keep-alive
Date: Mon, 28 Jun 2022 15:23:12 GMT
Server: tencent-ci
x-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"
}


错误码

该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。
中国站