本文介绍人脸检测与五官定位DetectFace的语法及示例。

功能描述

人脸检测与五官定位能力可以检测图片中的人脸并给出每张人脸定位和关键点信息。输出人脸数量、人脸矩形坐标、人脸姿态、双瞳孔中心坐标、人脸置信度列表等信息。支持检测含有多张人脸的照片。

您可以在体验中心进行体验与试用。

说明 阿里云视觉智能开放平台视觉AI能力API接入、接口使用或问题咨询等，请通过钉钉群（23109592）加入阿里云视觉智能开放平台咨询群联系我们。

应用场景

人脸关键点检测，是后续识别、分析和特效应用的基础。它为人脸识别、表情分析、疲劳检测、三维人脸重建、人脸美颜、换脸等人脸相关应用提供了人脸精确信息。

特色优势

  • 稠密关键点：提供105个关键点，足以应对人脸识别、姿态矫正、换脸等要求高精度人脸定位的应用。
  • 适应能力强：适应最大90度侧脸，平面360旋转人脸等情景。适用于各种应用场景。
  • 支持多人脸：支持在同张图中检测上千个人脸。

接入指引

1. 注册阿里云账号：打开阿里云官网，在阿里云官网右上角，单击立即注册，按照操作提示完成账号注册。

2. 开通能力：请确保您已开通人脸人体服务，若未开通服务请立即开通。

说明 本能力支持企业或个人认证用户开通。更多实名认证操作信息，请参见实名认证。

3. 创建AccessKey：请确保您已创建AccessKey，如果您使用的是子账号AccessKey，您需要给子账号赋予AliyunVIAPIFullAccess权限，具体操作，请参见RAM授权。

4. 在线调试（可选）：您可以通过OpenAPI Explorer在线调试能力，查看完整的调用示例代码及SDK依赖信息，也可以下载完整的工程。

5. 开发接入：能力支持SDK方式调用，您可以选择合适的开发语言进行接入，具体操作，请参见SDK总览。

输入限制

  • 图像格式：JPEG、JPG、PNG、BMP。
  • 图像大小：不超过3 MB。
  • 图像分辨率：大于32×32像素，小于4096×4096像素，人脸占比不低于64×64像素。
  • URL地址中不能包含中文字符。
说明 当图像分辨率超过最大限制时，请先将图片进行缩放，调整图片大小，具体请参见图片缩放。

计费说明

关于人脸检测与五官定位的计费方式及报价，请参见计费介绍。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String 是 DetectFace

系统规定参数。取值：DetectFace。

ImageURL String 是 http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/facebody/DetectFace/DetectFace1.png

图像URL地址。推荐使用上海地域的OSS链接，对于文件在本地或者非上海地域OSS链接的情况，请参见文件URL处理。

Landmark Boolean 否 true

是否需要返回人脸的特征点定位，取值true或false。
Quality Boolean 否 true

是否需要返回人脸质量，取值true或false。
Pose Boolean 否 true

是否需要返回人脸的姿态，取值true或false。
MaxFaceNumber Long 否 1

设置图片中人脸的最大返回数量，取值范围1~10。若想返回多个人脸检测结果，请正确设置。默认按返回参数FaceProbabilityList进行降序排列。

返回数据

名称 类型 示例值 描述
RequestId String E567D988-8072-43CF-B835-7AEF09FC5C1C

请求ID。
Data Object

返回的结果数据内容。
FaceProbabilityList Array of Float 0.99538141489028931

截图中包含人脸的概率，取值范围0~1。如有多个人脸，则依次返回。例如有两个人脸则返回[face_prob1, face_prob2]。图像中人脸区域分辨率越大，人脸越清晰，人脸正视，对应的该值越大。

Pupils Array of Float 232.2469482421875

左右两个瞳孔的中心点坐标和半径，每个人脸6个浮点数，顺序为[left_iris_cenpt.x, left_iris_cenpt.y, left_iris_radius, right_iris_cenpt.x, right_iris_cenpt.y, right_iris_radis]。

FaceRectangles Array of Integer [153,4,310,426]

返回人脸矩形框，分别是[left, top, width, height]。如有多个人脸，则依次顺延，返回矩形框。例如有两个人脸则返回[left1, top1, width1, height1, left2, top2, width2, height2]。

left-top: 表示以图片左上角为坐标原点，目标框所对应的左上角点位置（x,y），表示框的第一个点距离图片左边界x像素，距离上边界y个像素。

width-height：表示目标框的宽和高。

目标框面积为width*height，目标框右下角坐标为（left+width,top+heigth）。
FaceCount Integer 1

检测出的人脸个数。
PoseList Array of Float 0.86857914924621582

返回人脸姿态，格式为[yaw, pitch, roll]。如有多个人脸，则依次顺延。

  • yaw为左右角度，取值范围-90~90。
  • pitch为上下角度，取值范围-90~90。
  • roll为平面旋转角度，取值范围-180~180。
Landmarks Array of Float 179.71014404296875

人脸特征点定位结果，每个人脸返回一组特征点位置，表示方式为（x0, y0, x1, y1, ……）；如有多个人脸，则依次顺延，返回定位浮点数。

LandmarkCount Integer 105

人脸特征点数目，目前固定为105点。依次为：眉毛24点，眼睛32点，鼻子6点，嘴巴34点，外轮廓9点。
Qualities Object

人脸质量情况，分数越高表示越有利于识别。
ScoreList Array of Float 79.0

质量综合分数，分数越高越有利于识别，取值范围(0,100]。如有多张人脸，则依次返回。在识别时，推荐设置阈值大于等于85（您可以按实际应用场景判断设置阈值与否及相应阈值大小），大于85代表图片综合质量越高，小于85代表图片综合质量越低。
BlurList Array of Float 95.37

人脸模糊度对识别的影响分数，分数越高越有利于识别，取值范围(0,100]。如有多个人脸，则依次顺延。在识别时，推荐设置阈值大于等于85（您可以按实际应用场景判断设置阈值与否及相应阈值大小），大于85代表图片模糊的概率越低，小于85代表图片模糊的概率越高。
FnfList Array of Float 100

目标是否为人脸及其对识别的影响分数，分数越高越有利于识别，取值范围(0,100]。如有多个人脸，则依次顺延。在识别时，推荐设置阈值大于等于85（您可以按实际应用场景判断设置阈值与否及相应阈值大小），大于85代表图片是人脸的概率越高，小于85代表图片不是人脸的概率越低。
GlassList Array of Float 99.75

眼镜等上半脸遮挡对识别的影响分数，分数越高越有利于识别，取值范围(0,100]。如有多个人脸，则依次顺延。在识别时，推荐设置阈值大于等于85（您可以按实际应用场景判断设置阈值与否及相应阈值大小），大于85代表戴眼镜的概率越低，小于85代表戴眼镜的概率越高。
IlluList Array of Float 79.10

光照对识别的影响分数，分数越高越有利于识别，取值范围(0,100]。如有多个人脸，则依次顺延。在识别时，推荐设置阈值大于等于85（您可以按实际应用场景判断设置阈值与否及相应阈值大小），大于85代表图片光照好的概率越高，小于85代表图片光照好的概率越低。
MaskList Array of Float 88.3

口罩等下半脸遮挡对识别的影响分数，分数越高越有利于识别，取值范围(0,100]。如有多个人脸，则依次顺延。在识别时，推荐设置阈值大于等于85（您可以按实际应用场景判断设置阈值与否及相应阈值大小），大于85代表戴口罩概率越低，小于85代表戴口罩概率越高。
NoiseList Array of Float 77.39

图片噪声对识别的影响分数，分数越高越有利于识别，取值范围(0,100]。如有多个人脸，则依次顺延。在识别时，推荐设置阈值大于等于85（您可以按实际应用场景判断设置阈值与否及相应阈值大小），大于85代表图片有噪声的概率越低，小于85代表图片有噪声的概率越高。
PoseList Array of Float 99.82

姿态对识别的影响分数，分数越高越有利于识别，取值范围(0,100]。如有多个人脸，则依次顺延。在识别时，推荐设置阈值大于等于85（您可以按实际应用场景判断设置阈值与否及相应阈值大小），大于85代表人脸姿态正面的概率越高，小于85代表人脸姿态正面的概率越低。

示意图

  • 原图
  • 105关键点示意图

SDK参考

阿里云视觉AI能力推荐使用SDK调用，支持多种编程语言，文件参数通过SDK调用可支持本地文件及任意URL，具体可参见SDK总览。

示例

请求示例

http(s)://facebody.cn-shanghai.aliyuncs.com/?Action=DetectFace      //更多关于访问域名（Endpoint）信息，请参见：https://help.aliyun.com/document_detail/143103.html
&ImageURL=http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/facebody/DetectFace/DetectFace1.png
&Landmark=true
&Quality=true
&Pose=true
&MaxFaceNumber=1
&公共请求参数

正常返回示例

XML格式 

HTTP/1.1 200 OK
Content-Type:application/xml

<DetectFaceResponse>
    <RequestId>E567D988-8072-43CF-B835-7AEF09FC5C1C</RequestId>
    <Data>
        <FaceProbabilityList>0.929632306098938</FaceProbabilityList>
        <LandmarkCount>105</LandmarkCount>
        <FaceRectangles>144</FaceRectangles>
        <FaceRectangles>18</FaceRectangles>
        <FaceRectangles>326</FaceRectangles>
        <FaceRectangles>405</FaceRectangles>
        <Landmarks>177.1269073486328</Landmarks>
        <Landmarks>141.56689453125</Landmarks>
        <Landmarks>271.990478515625</Landmarks>
        <Landmarks>137.91294860839844</Landmarks>
        <Landmarks>223.6563262939453</Landmarks>
        <Landmarks>123.32662200927734</Landmarks>
        <Landmarks>224.28944396972656</Landmarks>
        <Landmarks>137.8303985595703</Landmarks>
        <Landmarks>190.42523193359375</Landmarks>
        <Landmarks>133.11012268066406</Landmarks>
        <Landmarks>206.60804748535156</Landmarks>
        <Landmarks>125.30608367919922</Landmarks>
        <Landmarks>240.8021240234375</Landmarks>
        <Landmarks>125.39529418945312</Landmarks>
        <Landmarks>257.24346923828125</Landmarks>
        <Landmarks>128.51979064941406</Landmarks>
        <Landmarks>191.29269409179688</Landmarks>
        <Landmarks>141.09840393066406</Landmarks>
        <Landmarks>207.5005645751953</Landmarks>
        <Landmarks>138.24703979492188</Landmarks>
        <Landmarks>240.81582641601562</Landmarks>
        <Landmarks>140.5307159423828</Landmarks>
        <Landmarks>257.2742004394531</Landmarks>
        <Landmarks>143.53077697753906</Landmarks>
        <Landmarks>343.474609375</Landmarks>
        <Landmarks>135.4432373046875</Landmarks>
        <Landmarks>441.0479736328125</Landmarks>
        <Landmarks>136.6552276611328</Landmarks>
        <Qualities>
            <NoiseList>96.94622039794922</NoiseList>
            <ScoreList>98.24667358398438</ScoreList>
            <BlurList>99.35592651367188</BlurList>
            <MaskList>99.75968170166016</MaskList>
            <GlassList>99.99040222167969</GlassList>
            <FnfList>100</FnfList>
            <PoseList>99.88871002197266</PoseList>
            <IlluList>99.84143829345703</IlluList>
        </Qualities>
        <FaceCount>1</FaceCount>
        <PoseList>0.2377411127090454</PoseList>
        <PoseList>1.8424458503723145</PoseList>
        <PoseList>0.3763512670993805</PoseList>
        <Pupils>232.3559112548828</Pupils>
        <Pupils>173.39218139648438</Pupils>
        <Pupils>18.214069366455078</Pupils>
        <Pupils>387.1202392578125</Pupils>
        <Pupils>174.74411010742188</Pupils>
        <Pupils>18.214069366455078</Pupils>
    </Data>
</DetectFaceResponse>

JSON格式 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "E567D988-8072-43CF-B835-7AEF09FC5C1C",
  "Data" : {
    "FaceProbabilityList" : 0.929632306098938,
    "LandmarkCount" : 105,
    "FaceRectangles" : [ 144, 18, 326, 405 ],
    "Landmarks" : [ 177.1269073486328, 141.56689453125, 271.990478515625, 137.91294860839844, 223.6563262939453, 123.32662200927734, 224.28944396972656, 137.8303985595703, 190.42523193359375, 133.11012268066406, 206.60804748535156, 125.30608367919922, 240.8021240234375, 125.39529418945312, 257.24346923828125, 128.51979064941406, 191.29269409179688, 141.09840393066406, 207.5005645751953, 138.24703979492188, 240.81582641601562, 140.5307159423828, 257.2742004394531, 143.53077697753906, 343.474609375, 135.4432373046875, 441.0479736328125, 136.6552276611328 ],
    "Qualities" : {
      "NoiseList" : 96.94622039794922,
      "ScoreList" : 98.24667358398438,
      "BlurList" : 99.35592651367188,
      "MaskList" : 99.75968170166016,
      "GlassList" : 99.99040222167969,
      "FnfList" : 100,
      "PoseList" : 99.88871002197266,
      "IlluList" : 99.84143829345703
    },
    "FaceCount" : 1,
    "PoseList" : [ 0.2377411127090454, 1.8424458503723145, 0.3763512670993805 ],
    "Pupils" : [ 232.3559112548828, 173.39218139648438, 18.214069366455078, 387.1202392578125, 174.74411010742188, 18.214069366455078 ]
  }
}

错误码

关于人脸检测与五官定位的错误码，详情请参见常见错误码。

安全声明

  • 请确保上传的图片或文件来源符合相应的法律法规。
  • 通过体验调试上传的临时文件有效期为1小时，在24小时后会被系统自动清理删除。
  • 平台不存储用户在使用服务过程中涉及的原始人脸图片或文件信息。