你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Face Detection Operations - Detect

参考

Service:: Azure AI Services

API Version:: v1.1-preview.1

检测图像中的人脸，返回人脸矩形以及可选的 faceId、地标和属性。

重要

为了减少可能使用户受到陈规定型观念、歧视或不公平拒绝服务的潜在滥用，我们将停用可预测情感、性别、年龄、微笑、面部毛发、头发和化妆的人脸 API 属性。阅读有关此决定 https://azure.microsoft.com/blog/responsible-ai-investments-and-safeguards-for-facial-recognition/的详细信息。

- 不会存储任何图像。只有提取的人脸特征 () 将存储在服务器上。 faceId 是人脸功能的标识符，将在“识别”、“验证”和“查找相似”中使用。在原始检测调用后，存储的人脸特征将在 faceIdTimeToLive 指定的时间过期并被删除。
- 可选参数包括 faceId、陆标和属性。属性包括 headPose、眼镜、遮挡、配件、模糊、曝光、噪音、掩码和 qualityForRecognition。为特定属性返回的某些结果可能不太准确。
- 支持 JPEG、PNG、GIF (第一帧) 和 BMP 格式。允许的图像文件大小为 1KB 到 6MB。
- 在不超过 1920x1080 像素的图像中，最小可检测人脸大小为 36x36 像素。尺寸大于 1920x1080 像素的图像需要按比例增大最小人脸大小。
- 一张图像最多可以返回 100 张人脸。人脸将根据人脸矩形大小按从大到小的顺序排序。
- 若要在查询“Identify”、“Verify”和“Find Similar” ('returnFaceId'为 true) 时获得最佳结果，请使用正面、清晰且最小大小为 200x200 像素 (眼睛) 之间的 100 像素的人脸。
- 可以提供不同的“detectionModel”值。若要使用和比较不同的检测模型，请参阅 https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model
  - “detection_02”：如果选择此检测模型，则禁用人脸属性和特征点。
  - “detection_03”：如果选择此检测模型，则支持人脸属性 (掩码、模糊和 headPose) 和陆标。
- 提供了不同的“recognitionModel”值。如果需要“验证”、“标识”、“查找相似”等后续操作，请使用“recognitionModel”参数指定识别模型。 “recognitionModel”的默认值为“recognition_01”，如果需要最新模型，请在此参数中显式指定所需的模型。指定后，检测到的 faceId 将与指定的识别模型相关联。有关详细信息，请参阅 https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-recognition-model。

POST {endpoint}/face/{apiVersion}/detect

With optional parameters:

POST {endpoint}/face/{apiVersion}/detect?_overload=detect&detectionModel={detectionModel}&recognitionModel={recognitionModel}&returnFaceId={returnFaceId}&returnFaceAttributes={returnFaceAttributes}&returnFaceLandmarks={returnFaceLandmarks}&returnRecognitionModel={returnRecognitionModel}&faceIdTimeToLive={faceIdTimeToLive}

URI 参数

名称	在	必需	类型	说明
apiVersion	path	True	string	API 版本
endpoint	path	True	string uri	支持的认知服务终结点 (协议和主机名，例如：https://{resource-name}.cognitiveservices.azure.com) 。
detectionModel	query		DetectionModel	与检测到的 faceId 关联的“detectionModel”。支持的“detectionModel”值包括“detection_01”、“detection_02”和“detection_03”。默认值为“detection_01”。
faceIdTimeToLive	query		integer int32	正在缓存的人脸 ID 的秒数。支持的范围从 60 秒到 86400 秒不等。默认值为 86400（24 小时）。
recognitionModel	query		RecognitionModel	与检测到的 faceId 关联的“recognitionModel”。支持的“recognitionModel”值包括“recognition_01”、“recognition_02”、“recognition_03”或“recognition_04”。默认值为“recognition_01”。建议使用“recognition_04”，因为与“recognition_03”相比，戴口罩的人脸的准确度有所提高，与“recognition_01”和“recognition_02”相比，其整体准确度也得到了提高。
returnFaceAttributes	query		FaceAttributeType[]	分析并返回逗号分隔字符串中的一个或多个指定人脸属性，例如“returnFaceAttributes=headPose，眼镜”。人脸属性分析具有额外的计算和时间成本。
returnFaceId	query		boolean	返回是否检测到的人脸的 faceIds。默认值为 true。
returnFaceLandmarks	query		boolean	返回是否检测到的人脸的人脸特征点。默认值为 false。
returnRecognitionModel	query		boolean	是否返回“recognitionModel”。默认值为 false。仅当 returnFaceId = true 时，这才适用。

请求正文

Media Types: "application/octet-stream"

名称	类型	说明
imageContent	string	输入图像二进制文件。

响应

名称	类型	说明
200 OK	FaceDetectionResult[]	成功的调用将返回按人脸矩形大小按降序排列的人脸条目数组。空响应表示未检测到人脸。
Other Status Codes	FaceErrorResponse	意外的错误响应。 Headers x-ms-error-code: string

名称

类型

说明

200 OK

FaceDetectionResult[]

成功的调用将返回按人脸矩形大小按降序排列的人脸条目数组。空响应表示未检测到人脸。

Other Status Codes

FaceErrorResponse

意外的错误响应。

Headers

x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

Azure AI 人脸订阅的密钥。

Type: apiKey
In: header

AADToken

Azure Active Directory OAuth2 流

Type: oauth2
Flow: accessCode
Authorization URL: https://api.example.com/oauth2/authorize
Token URL: https://api.example.com/oauth2/token

Scopes

名称	说明
https://cognitiveservices.azure.com/.default

示例

Detect with Image

Sample Request

HTTP

POST {endpoint}/face/v1.1-preview.1/detect?_overload=detect&detectionModel=detection_01&recognitionModel=recognition_03&returnFaceId=True&returnFaceAttributes=glasses,headPose,occlusion,accessories,blur,exposure,noise,qualityForRecognition&returnFaceLandmarks=True&returnRecognitionModel=True&faceIdTimeToLive=60

"<your-image-bytes-here>"

Sample Response

Status code:: 200

[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "recognitionModel": "recognition_03",
    "faceRectangle": {
      "width": 78,
      "height": 78,
      "left": 394,
      "top": 54
    },
    "faceLandmarks": {
      "pupilLeft": {
        "x": 412.7,
        "y": 78.4
      },
      "pupilRight": {
        "x": 446.8,
        "y": 74.2
      },
      "noseTip": {
        "x": 437.7,
        "y": 92.4
      },
      "mouthLeft": {
        "x": 417.8,
        "y": 114.4
      },
      "mouthRight": {
        "x": 451.3,
        "y": 109.3
      },
      "eyebrowLeftOuter": {
        "x": 397.9,
        "y": 78.5
      },
      "eyebrowLeftInner": {
        "x": 425.4,
        "y": 70.5
      },
      "eyeLeftOuter": {
        "x": 406.7,
        "y": 80.6
      },
      "eyeLeftTop": {
        "x": 412.2,
        "y": 76.2
      },
      "eyeLeftBottom": {
        "x": 413,
        "y": 80.1
      },
      "eyeLeftInner": {
        "x": 418.9,
        "y": 78
      },
      "eyebrowRightInner": {
        "x": 4.8,
        "y": 69.7
      },
      "eyebrowRightOuter": {
        "x": 5.5,
        "y": 68.5
      },
      "eyeRightInner": {
        "x": 441.5,
        "y": 75
      },
      "eyeRightTop": {
        "x": 446.4,
        "y": 71.7
      },
      "eyeRightBottom": {
        "x": 447,
        "y": 75.3
      },
      "eyeRightOuter": {
        "x": 451.7,
        "y": 73.4
      },
      "noseRootLeft": {
        "x": 428,
        "y": 77.1
      },
      "noseRootRight": {
        "x": 435.8,
        "y": 75.6
      },
      "noseLeftAlarTop": {
        "x": 428.3,
        "y": 89.7
      },
      "noseRightAlarTop": {
        "x": 442.2,
        "y": 87
      },
      "noseLeftAlarOutTip": {
        "x": 424.3,
        "y": 96.4
      },
      "noseRightAlarOutTip": {
        "x": 446.6,
        "y": 92.5
      },
      "upperLipTop": {
        "x": 437.6,
        "y": 105.9
      },
      "upperLipBottom": {
        "x": 437.6,
        "y": 108.2
      },
      "underLipTop": {
        "x": 436.8,
        "y": 111.4
      },
      "underLipBottom": {
        "x": 437.3,
        "y": 114.5
      }
    },
    "faceAttributes": {
      "glasses": "sunglasses",
      "headPose": {
        "roll": 2.1,
        "yaw": 3,
        "pitch": 1.6
      },
      "occlusion": {
        "foreheadOccluded": false,
        "eyeOccluded": false,
        "mouthOccluded": false
      },
      "accessories": [
        {
          "type": "headwear",
          "confidence": 0.99
        },
        {
          "type": "glasses",
          "confidence": 1
        },
        {
          "type": "mask",
          "confidence": 0.87
        }
      ],
      "blur": {
        "blurLevel": "medium",
        "value": 0.51
      },
      "exposure": {
        "exposureLevel": "goodExposure",
        "value": 0.55
      },
      "noise": {
        "noiseLevel": "low",
        "value": 0.12
      },
      "qualityForRecognition": "high"
    }
  }
]

定义

名称	说明
AccessoryItem	附件项和相应的置信度级别。
AccessoryType	附件的类型。
BlurLevel	指示模糊级别。
BlurProperties	描述图像中是否存在任何模糊的属性。
DetectionModel	与检测到的 faceId 关联的“detectionModel”。支持的“detectionModel”值包括“detection_01”、“detection_02”和“detection_03”。默认值为“detection_01”。
ExposureLevel	指示曝光级别。
ExposureProperties	描述图像曝光级别的属性。
FaceAttributes	检测到的人脸的人脸属性。
FaceAttributeType	分析并返回逗号分隔字符串中的一个或多个指定人脸属性，例如“returnFaceAttributes=headPose，眼镜”。人脸属性分析具有额外的计算和时间成本。
FaceDetectionResult	检测 API 的响应。
FaceError	错误对象。有关人脸服务返回的错误代码和消息的完整详细信息，请参阅以下链接： https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含错误详细信息的响应。
FaceLandmarks	指向人脸组件重要位置的 27 点人脸特征点的集合。
FaceRectangle	可在其中找到人脸的矩形。
FacialHair	描述面部毛发属性的属性。
GlassesType	人脸的眼镜类型。
HairColor	候选颜色的数组和每个颜色的置信度。
HairColorType	头发颜色的名称。
HairProperties	描述头发属性的属性。
HeadPose	人脸方向的三维滚动/偏航/俯仰角。
LandmarkCoordinate	图像中的陆标坐标。
MaskProperties	描述给定人脸上是否存在掩码的属性。
MaskType	掩码的类型。
NoiseLevel	指示噪音级别。
NoiseProperties	描述图像噪音级别的属性。
OcclusionProperties	描述给定人脸上的遮挡的属性。
QualityForRecognition	指示用于识别的图像质量。
RecognitionModel	人脸的识别模型。

AccessoryItem

附件项和相应的置信度级别。

名称	类型	说明
confidence	number	附件类型的置信度。范围在 [0,1] 之间。
type	AccessoryType	附件的类型。

AccessoryType

附件的类型。

名称	类型	说明
glasses	string	眼镜。
headwear	string	头戴。
mask	string	面具。

BlurLevel

指示模糊级别。

名称	类型	说明
high	string	高模糊级别。
low	string	低模糊级别。
medium	string	中等模糊级别。

BlurProperties

描述图像中是否存在任何模糊的属性。

名称	类型	说明
blurLevel	BlurLevel	指示模糊级别的枚举值。
value	number	一个数字，指示从 0 到 1 的模糊程度。

DetectionModel

与检测到的 faceId 关联的“detectionModel”。支持的“detectionModel”值包括“detection_01”、“detection_02”和“detection_03”。默认值为“detection_01”。

名称	类型	说明
detection_01	string	默认检测模型。建议用于近正面人脸检测。对于角异常大 (头部姿势) 人脸、遮挡人脸或图像方向错误的场景，可能无法检测到此类情况下的人脸。
detection_02	string	检测模型于 2019 年 5 月发布，准确度有所提高，尤其是在小面、侧脸和模糊人脸上。
detection_03	string	检测模型于 2021 年 2 月发布，准确度有所提高，尤其是在小人脸上。

ExposureLevel

指示曝光级别。

名称	类型	说明
goodExposure	string	良好的曝光级别。
overExposure	string	高曝光级别。
underExposure	string	低曝光级别。

ExposureProperties

描述图像曝光级别的属性。

名称	类型	说明
exposureLevel	ExposureLevel	指示曝光级别的枚举值。
value	number	一个数字，指示从 0 到 1 的曝光级别。 [0， 0.25) 处于暴露之下。 [0.25， 0.75) 曝光良好。 [0.75， 1] 曝光过度。

FaceAttributes

检测到的人脸的人脸属性。

名称	类型	说明
accessories	AccessoryItem[]	描述给定面上任何附件的属性。
age	number	年龄（以年为单位）。
blur	BlurProperties	描述图像中是否存在任何模糊的属性。
exposure	ExposureProperties	描述图像曝光级别的属性。
facialHair	FacialHair	描述面部毛发属性的属性。
glasses	GlassesType	眼镜键入，如果有一个脸。
hair	HairProperties	描述头发属性的属性。
headPose	HeadPose	人脸方向的三维滚动/偏航/俯仰角。
mask	MaskProperties	描述给定人脸上是否存在掩码的属性。
noise	NoiseProperties	描述图像噪音级别的属性。
occlusion	OcclusionProperties	描述给定人脸上的遮挡的属性。
qualityForRecognition	QualityForRecognition	描述有关检测中使用的图像的质量是否足以尝试进行人脸识别的整个图像质量的属性。
smile	number	微笑强度，介于 [0,1] 之间的数字。

FaceAttributeType

分析并返回逗号分隔字符串中的一个或多个指定人脸属性，例如“returnFaceAttributes=headPose，眼镜”。人脸属性分析具有额外的计算和时间成本。

名称	类型	说明
accessories	string	面部周围的配件，包括“头饰”、“眼镜”和“面具”。空数组表示未检测到任何附件。请注意，这是在检测到人脸之后。大掩码可能导致未检测到人脸。
age	string	年龄（以年为单位）。
blur	string	人脸模糊与否。 Level 返回“Low”、“Medium”或“High”。值返回一个介于 [0,1] 之间的数字，越模糊越大。
exposure	string	人脸曝光级别。 Level 返回“GoodExposure”、“OverExposure”或“UnderExposure”。
facialHair	string	描述面部毛发属性的属性。
glasses	string	眼镜类型。值包括“NoGlasses”、“ReadingGlasses”、“Sunglasses”、“SwimmingGoggles”。
hair	string	描述头发属性的属性。
headPose	string	人脸方向的三维滚动/偏航/俯仰角。
mask	string	每张脸是否都戴着面具。掩码类型返回“noMask”、“faceMask”、“otherMaskOrOcclusion”或“不确定”。值返回一个布尔值“noseAndMouthCovered”，指示是否覆盖鼻子和嘴。
noise	string	人脸像素的噪声级别。 Level 返回“Low”、“Medium”和“High”。值返回一个介于 [0,1] 之间的数字，越大，
occlusion	string	每个面部区域是否被遮挡，包括额头、眼睛和嘴巴。
qualityForRecognition	string	有关检测中使用的图像是否具有足够的质量来尝试进行人脸识别的总体图像质量。非正式评级值为低、中或高。对于人员注册，建议仅使用“高”质量图像，对于识别方案，建议使用“中等”或更高质量的图像。仅当使用识别模型recognition_03或recognition_04时，属性才可用。
smile	string	微笑强度，介于 [0,1] 之间的数字。

FaceDetectionResult

检测 API 的响应。

名称	类型	说明
faceAttributes	FaceAttributes	检测到的人脸的人脸属性。
faceId	string	检测到的人脸的唯一 faceId，由检测 API 创建，将在检测调用后 24 小时过期。若要返回此值，它要求“returnFaceId”参数为 true。
faceLandmarks	FaceLandmarks	一系列（27 个点）人脸特征点，这些特征点指向人脸组件的重要位置。若要返回此值，它要求“returnFaceLandmarks”参数为 true。
faceRectangle	FaceRectangle	图像上人脸位置的矩形区域。
recognitionModel	RecognitionModel	与此 faceId 关联的“recognitionModel”。仅当“returnRecognitionModel”显式设置为 true 时，才会返回此值。

FaceError

错误对象。有关人脸服务返回的错误代码和消息的完整详细信息，请参阅以下链接： https://aka.ms/face-error-codes-and-messages。

名称	类型	说明
code	string	服务器定义的一组错误代码中的一个。
message	string	错误的用户可读表示形式。

FaceErrorResponse

包含错误详细信息的响应。

名称	类型	说明
error	FaceError	错误对象。

FaceLandmarks

指向人脸组件重要位置的 27 点人脸特征点的集合。

名称	类型	说明
eyeLeftBottom	LandmarkCoordinate	左眼底部的坐标。
eyeLeftInner	LandmarkCoordinate	左眼内部的坐标。
eyeLeftOuter	LandmarkCoordinate	左眼外部的坐标。
eyeLeftTop	LandmarkCoordinate	左眼顶部的坐标。
eyeRightBottom	LandmarkCoordinate	右眼底部的坐标。
eyeRightInner	LandmarkCoordinate	右眼内部的坐标。
eyeRightOuter	LandmarkCoordinate	右眼外部的坐标。
eyeRightTop	LandmarkCoordinate	右眼顶部的坐标。
eyebrowLeftInner	LandmarkCoordinate	左眉内部的坐标。
eyebrowLeftOuter	LandmarkCoordinate	左眉外部的坐标。
eyebrowRightInner	LandmarkCoordinate	右眉内部的坐标。
eyebrowRightOuter	LandmarkCoordinate	右眉外侧的坐标。
mouthLeft	LandmarkCoordinate	左嘴的坐标。
mouthRight	LandmarkCoordinate	右嘴的坐标。
noseLeftAlarOutTip	LandmarkCoordinate	鼻子左尖的坐标。
noseLeftAlarTop	LandmarkCoordinate	鼻子左上部的坐标。
noseRightAlarOutTip	LandmarkCoordinate	鼻子右外尖的坐标。
noseRightAlarTop	LandmarkCoordinate	鼻子右上部的坐标。
noseRootLeft	LandmarkCoordinate	左鼻根的坐标。
noseRootRight	LandmarkCoordinate	右鼻根的坐标。
noseTip	LandmarkCoordinate	鼻尖的坐标。
pupilLeft	LandmarkCoordinate	左眼孔的坐标。
pupilRight	LandmarkCoordinate	右眼孔的坐标。
underLipBottom	LandmarkCoordinate	下唇底部的坐标。
underLipTop	LandmarkCoordinate	下唇顶的坐标。
upperLipBottom	LandmarkCoordinate	上唇底部的坐标。
upperLipTop	LandmarkCoordinate	上唇顶的坐标。

FaceRectangle

可在其中找到人脸的矩形。

名称	类型	说明
height	integer	矩形的高度（以像素为单位）。
left	integer	图像到矩形左边缘的距离（以像素为单位）。
top	integer	图像到矩形上边缘的距离（以像素为单位）。
width	integer	矩形的宽度（以像素为单位）。

FacialHair

描述面部毛发属性的属性。

名称	类型	说明
beard	number	一个介于 0 到 1 的范围的数字，指示与属性关联的置信度。
moustache	number	一个介于 0 到 1 的范围的数字，指示与属性关联的置信度。
sideburns	number	一个介于 0 到 1 的范围的数字，指示与属性关联的置信度。

GlassesType

人脸的眼镜类型。

名称	类型	说明
noGlasses	string	脸上没有眼镜。
readingGlasses	string	脸上的正常眼镜。
sunglasses	string	脸上的太阳镜。
swimmingGoggles	string	脸上的游泳护目镜。

HairColor

候选颜色的数组和每个颜色的置信度。

名称	类型	说明
color	HairColorType	头发颜色的名称。
confidence	number	颜色的置信度。范围在 [0,1] 之间。

HairColorType

头发颜色的名称。

名称	类型	说明
black	string	黑。
blond	string	金发。
brown	string	棕色。
gray	string	灰色。
other	string	其他。
red	string	红。
unknown	string	未知。
white	string	白色。

HairProperties

描述头发属性的属性。

名称	类型	说明
bald	number	描述此人是否秃顶的置信度的数字。
hairColor	HairColor[]	候选颜色的数组和每个颜色的置信度。
invisible	boolean	描述头发在图像中是否可见的布尔值。

HeadPose

人脸方向的三维滚动/偏航/俯仰角。

名称	类型	说明
pitch	number	角度的值。
roll	number	角度的值。
yaw	number	角度的值。

LandmarkCoordinate

图像中的陆标坐标。

名称	类型	说明
x	number	水平分量（以像素为单位）。
y	number	垂直分量（以像素为单位）。

MaskProperties

描述给定人脸上是否存在掩码的属性。

名称	类型	说明
noseAndMouthCovered	boolean	一个布尔值，指示是否覆盖鼻子和嘴巴。
type	MaskType	掩码的类型。

MaskType

掩码的类型。

名称	类型	说明
faceMask	string	面罩。
noMask	string	没有掩码。
otherMaskOrOcclusion	string	其他类型的掩码或遮挡。
uncertain	string	不确定性。

NoiseLevel

指示噪音级别。

名称	类型	说明
high	string	高噪音级别。
low	string	低噪音级别。
medium	string	中等噪音级别。

NoiseProperties

描述图像噪音级别的属性。

名称	类型	说明
noiseLevel	NoiseLevel	指示噪音级别的枚举值。
value	number	一个数字，指示介于 0 到 1 的噪音级别。 [0， 0.25) 处于暴露之下。 [0.25， 0.75) 曝光良好。 [0.75， 1] 曝光过度。 [0， 0.3) 为低噪音级别。 [0.3， 0.7) 为中等噪音级别。 [0.7， 1] 是高噪音级别。

OcclusionProperties

描述给定人脸上的遮挡的属性。

名称	类型	说明
eyeOccluded	boolean	一个布尔值，指示眼睛是否被遮挡。
foreheadOccluded	boolean	一个布尔值，指示额头是否遮挡。
mouthOccluded	boolean	一个布尔值，指示嘴是否被遮挡。

QualityForRecognition

指示用于识别的图像质量。

名称	类型	说明
high	string	高质量。
low	string	低质量。
medium	string	中等质量。

RecognitionModel

人脸的识别模型。

名称	类型	说明
recognition_01	string	“Detect”的默认识别模型。在 2019 年 3 月之前创建的所有 faceId 都与此识别模型绑定。
recognition_02	string	2019 年 3 月发布的识别模型。
recognition_03	string	识别模型于 2020 年 5 月发布。
recognition_04	string	识别模型于 2021 年 2 月发布。建议使用此识别模型来提高识别准确性。

通过

Face Detection Operations - Detect

URI 参数

请求正文

响应

安全性

Ocp-Apim-Subscription-Key

AADToken

Scopes

示例

Detect with Image

Sample Request

Sample Response

定义

AccessoryItem

AccessoryType

BlurLevel

BlurProperties

DetectionModel

ExposureLevel

ExposureProperties

FaceAttributes

FaceAttributeType

FaceDetectionResult

FaceError

FaceErrorResponse

FaceLandmarks

FaceRectangle

FacialHair

GlassesType

HairColor

HairColorType

HairProperties

HeadPose

LandmarkCoordinate

MaskProperties

MaskType

NoiseLevel

NoiseProperties

OcclusionProperties

QualityForRecognition

RecognitionModel

其他资源