人脸检测与分析

1. 接口描述

接口请求域名： iai.tencentcloudapi.com 。

检测给定图片中的人脸（Face）的位置、相应的面部属性和人脸质量信息，位置包括 (x，y，w，h)，面部属性包括性别（gender）、年龄（age）、表情（expression）、魅力（beauty）、眼镜（glass）、发型（hair）、口罩（mask）和姿态 (pitch，roll，yaw)，人脸质量信息包括整体质量分（score）、模糊分（sharpness）、光照分（brightness）和五官遮挡分（completeness）。

其中，人脸质量信息主要用于评价输入的人脸图片的质量。在使用人脸识别服务时，建议您对输入的人脸图片进行质量检测，提升后续业务处理的效果。该功能的应用场景包括：

1） 人员库创建人员/增加人脸：保证人员人脸信息的质量，便于后续的业务处理。

2） 人脸搜索：保证输入的图片质量，快速准确匹配到对应的人员。

3） 人脸验证：保证人脸信息的质量，避免明明是本人却认证不通过的情况。

4） 人脸融合：保证上传的人脸质量，人脸融合的效果更好。

• 公共参数中的签名方式请使用V3版本，即配置SignatureMethod参数为TC3-HMAC-SHA256。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

3. 输出参数

4. 示例

示例1 人脸检测与分析接口成功

检测给定图片中的人脸的位置、相应的面部属性和人脸质量信息。

输入示例

https://iai.tencentcloudapi.com/?Action=DetectFace
&MaxFaceNum=1
&MinFaceSize=40
&Url=http://test.image.myqcloud.com/testB.jpg
&NeedFaceAttributes=0
&NeedQualityDetection=0
&<公共请求参数>

输出示例

{
    "Response": {
        "ImageWidth": 640,
        "ImageHeight": 440,
        "FaceInfos": [
            {
                "X": 156,
                "Y": 129,
                "Width": 196,
                "Height": 196,
                "FaceAttributesInfo": {
                    "Gender": 0,
                    "Age": 0,
                    "Expression": 0,
                    "Hat": false,
                    "Glass": false,
                    "EyeOpen": true,
                    "Mask": false,
                    "Hair": {
                        "Length": 0,
                        "Bang": 0,
                        "Color": 0
                    },
                    "Pitch": 0,
                    "Yaw": 0,
                    "Roll": 0,
                    "Beauty": 0
                },
                "FaceQualityInfo": {
                    "Score": 0,
                    "Sharpness": 0,
                    "Brightness": 0,
                    "Completeness": {
                        "Eyebrow": 0,
                        "Eye": 0,
                        "Nose": 0,
                        "Cheek": 0,
                        "Mouth": 0,
                        "Chin": 0
                    }
                }
            }
        ],
        "FaceModelVersion": "3.0",
        "RequestId": "a574102d-1b86-48a7-a08b-6a741a8fedb6"
    }
}

示例2 人脸检测与分析接口成功示例

检测给定图片中的人脸的位置、相应的面部属性和人脸质量信息。

输入示例

https://iai.tencentcloudapi.com/?Action=DetectFace
&MaxFaceNum=1
&MinFaceSize=40
&Url=http://test.image.myqcloud.com/testA.jpg
&NeedFaceAttributes=1
&NeedQualityDetection=1
&<公共请求参数>

输出示例

{
    "Response": {
        "ImageWidth": 640,
        "ImageHeight": 440,
        "FaceInfos": [
            {
                "X": 156,
                "Y": 129,
                "Width": 196,
                "Height": 196,
                "FaceAttributesInfo": {
                    "Gender": 99,
                    "Age": 51,
                    "Expression": 99,
                    "Hat": false,
                    "Glass": false,
                    "EyeOpen": true,
                    "Mask": true,
                    "Hair": {
                        "Length": 1,
                        "Bang": 1,
                        "Color": 0
                    },
                    "Pitch": 17,
                    "Yaw": 5,
                    "Roll": -2,
                    "Beauty": 71
                },
                "FaceQualityInfo": {
                    "Score": 63,
                    "Sharpness": 73,
                    "Brightness": 47,
                    "Completeness": {
                        "Eyebrow": 99,
                        "Eye": 99,
                        "Nose": 99,
                        "Cheek": 52,
                        "Mouth": 99,
                        "Chin": 47
                    }
                }
            }
        ],
        "FaceModelVersion": "3.0",
        "RequestId": "bcde47b5-e6d8-446e-a538-bcecffbe306a"
    }
}

示例3 人脸检测与分析接口失败示例

传入无人脸图片，检测人脸的位置、相应的面部属性和人脸质量信息。

输入示例

https://iai.tencentcloudapi.com/?Action=DetectFace
&MaxFaceNum=1
&MinFaceSize=40
&Url=http://test.image.myqcloud.com/testA.jpg
&NeedFaceAttributes=1
&NeedQualityDetection=1
&<公共请求参数>

输出示例

{
    "Response": {
        "RequestId": "54eedbca-8704-4388-9b1c-4bdf1a4308a4",
        "Error": {
            "Code": "InvalidParameterValue.NoFaceInPhoto",
            "Message": "图片中没有人脸。"
        }
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

• Tencent Cloud SDK 3.0 for Python: GitHub Gitee
• Tencent Cloud SDK 3.0 for Java: GitHub Gitee
• Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
• Tencent Cloud SDK 3.0 for Go: GitHub Gitee
• Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
• Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
• Tencent Cloud SDK 3.0 for C++: GitHub Gitee
• Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee

命令行工具

• Tencent Cloud CLI 3.0

6. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。