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

Face - Detect With Url

参考

服务:: Azure AI Services

API 版本:: 1.0

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

不会存储任何图像。仅提取的人脸功能将存储在服务器上。 faceId 是人脸功能的标识符，将用于人脸 - 识别、人脸 - 验证和人脸 - 查找类似的。存储的人脸功能将在原始检测调用后由 faceIdTimeToLive 指定的时间过期并被删除。
可选参数包括 faceId、地标和属性。属性包括年龄、性别、headPose、微笑、面部海尔、眼镜、情感、头发、化妆、遮挡、配件、模糊、曝光、噪音、面具和质量ForRecognition。为特定属性返回的某些结果可能不太准确。
支持 JPEG、PNG、GIF（第一帧）和 BMP 格式。允许的图像文件大小从 1KB 到 6MB。
最多可以返回 100 张人脸作为图像。人脸按从大到小的人脸矩形大小进行排名。
若要获得最佳结果，请在查询人脸 - 识别、人脸 - 验证和人脸 - 查找相似（'returnFaceId'为 true），请使用正面、清晰且最小大小为 200x200 像素（眼睛之间的 100 像素）的人脸。
最小可检测人脸大小在图像中不超过 1920x1080 像素的 36x36 像素。尺寸高于 1920x1080 像素的图像将需要比例更大的最小人脸大小。
可以提供不同的“detectionModel”值。若要使用和比较不同的检测模型，请参阅如何指定检测模型。
提供了不同的“recognitionModel”值。如果需要后续作（如验证、识别、查找相似），请使用“recognitionModel”参数指定识别模型。 “recognitionModel”的默认值为“recognition_01”，如果需要最新的模型，请显式指定此参数中所需的模型。指定后，检测到的 faceId 将与指定的识别模型相关联。有关详细信息，请参阅指定识别模型。

POST {Endpoint}/face/v1.0/detect

具有可选参数:

POST {Endpoint}/face/v1.0/detect?returnFaceId={returnFaceId}&returnFaceLandmarks={returnFaceLandmarks}&returnFaceAttributes={returnFaceAttributes}&recognitionModel={recognitionModel}&returnRecognitionModel={returnRecognitionModel}&detectionModel={detectionModel}&faceIdTimeToLive={faceIdTimeToLive}

URI 参数

名称	在	必需	类型	说明
Endpoint	path	True	string	支持的认知服务终结点（协议和主机名，例如：https://westus.api.cognitive.microsoft.com）。
detectionModel	query		DetectionModel	检测模型的名称。检测模型用于检测提交的图像中的人脸。执行人脸 - 检测或（大型）FaceList - 添加人脸或（大型）PersonGroup - 添加人脸时，可以提供检测模型名称。默认值为“detection_01”，如果需要另一个模型，请显式指定它。
faceIdTimeToLive	query		integer minimum: 60 maximum: 86400	正在缓存 faceId 的秒数。支持的范围从 60 秒到 86400 秒。默认值为 86400 （24 小时）。
recognitionModel	query		RecognitionModel	识别模型的名称。提取人脸特征并与检测到的 faceId、（Large）FaceList 或（Large）PersonGroup 相关联时，将使用识别模型。执行人脸 - 检测或（大型）FaceList - 创建或（大型）PersonGroup - 创建时，可以提供识别模型名称。默认值为“recognition_01”，如果需要最新模型，请显式指定所需的模型。
returnFaceAttributes	query		FaceAttributeType[]	分析和返回逗号分隔字符串中的一个或多个指定人脸属性，例如“returnFaceAttributes=age，gender”。可用属性取决于指定的“detectionModel”。 “detection_01”支持年龄、性别、headPose、微笑、面部海尔、眼镜、情感、头发、化妆、遮挡、配件、模糊、暴露、噪音和质量ForRecognition。虽然“detection_02”不支持任何属性，“detection_03”仅支持 mask 和 qualityForRecognition。此外，仅当“recognitionModel”指定为“recognition_03”或“recognition_04”时，才支持 qualityForRecognition。请注意，每个人脸属性分析都有额外的计算和时间成本。
returnFaceId	query		boolean	一个值，该值指示作是否应返回检测到的人脸的 faceId。检测此值设置为 true 需要 https://aka.ms/facerecognition进行额外的访问审批。
returnFaceLandmarks	query		boolean	一个值，该值指示作是否应返回检测到的人脸的地标。
returnRecognitionModel	query		boolean	一个值，该值指示作是否应在响应中返回“recognitionModel”。

请求头

名称	必需	类型	说明
Ocp-Apim-Subscription-Key	True	string

请求正文

名称	必需	类型	说明
url	True	string	图像的可公开访问 URL

响应

名称	类型	说明
200 OK	DetectedFace[]	成功的调用以降序返回按人脸矩形大小排名的人脸条目数组。空响应指示未检测到人脸。
Other Status Codes	APIError	错误响应。

安全性

Ocp-Apim-Subscription-Key

类型: apiKey
在: header

示例

Detect with url example

示例请求

HTTP

POST {Endpoint}/face/v1.0/detect?returnFaceAttributes=age,gender,headPose,smile,facialHair,glasses,emotion,hair,makeup,occlusion,accessories,blur,exposure,noise&recognitionModel=recognition_01&returnRecognitionModel=True&detectionModel=detection_01


{
  "url": "{Image Url here}"
}

示例响应

状态代码:: 200

[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "recognitionModel": "recognition_01",
    "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": {
      "age": 71,
      "gender": "male",
      "smile": 0.88,
      "facialHair": {
        "moustache": 0.8,
        "beard": 0.1,
        "sideburns": 0.02
      },
      "glasses": "sunglasses",
      "headPose": {
        "roll": 2.1,
        "yaw": 3,
        "pitch": 1.6
      },
      "emotion": {
        "anger": 0.575,
        "contempt": 0,
        "disgust": 0.006,
        "fear": 0.008,
        "happiness": 0.394,
        "neutral": 0.013,
        "sadness": 0,
        "surprise": 0.004
      },
      "hair": {
        "bald": 0,
        "invisible": false,
        "hairColor": [
          {
            "color": "brown",
            "confidence": 1
          },
          {
            "color": "blond",
            "confidence": 0.88
          },
          {
            "color": "black",
            "confidence": 0.48
          },
          {
            "color": "other",
            "confidence": 0.11
          },
          {
            "color": "gray",
            "confidence": 0.07
          },
          {
            "color": "red",
            "confidence": 0.03
          }
        ]
      },
      "makeup": {
        "eyeMakeup": true,
        "lipMakeup": false
      },
      "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
      }
    }
  }
]

定义

名称	说明
Accessory	附件项和相应的置信度。
AccessoryType	附件的类型
APIError	API 返回的错误信息
Blur	描述图像中存在模糊状态的属性。
BlurLevel	一个指示模糊级别的枚举值。
Coordinate	图像中的坐标
DetectedFace	检测到的人脸对象。
DetectionModel	检测模型的名称。检测模型用于检测提交的图像中的人脸。执行人脸 - 检测或（大型）FaceList - 添加人脸或（大型）PersonGroup - 添加人脸时，可以提供检测模型名称。默认值为“detection_01”，如果需要另一个模型，请显式指定它。
Emotion	描述面部情感的属性，其置信度从 0 到 1 不等。
Error	错误正文。
Exposure	描述图像曝光级别的属性。
ExposureLevel	指示曝光级别的枚举值。
FaceAttributes	人脸属性
FaceAttributeType	分析和返回逗号分隔字符串中的一个或多个指定人脸属性，例如“returnFaceAttributes=age，gender”。可用属性取决于指定的“detectionModel”。 “detection_01”支持年龄、性别、headPose、微笑、面部海尔、眼镜、情感、头发、化妆、遮挡、配件、模糊、暴露、噪音和质量ForRecognition。虽然“detection_02”不支持任何属性，“detection_03”仅支持 mask 和 qualityForRecognition。此外，仅当“recognitionModel”指定为“recognition_03”或“recognition_04”时，才支持 qualityForRecognition。请注意，每个人脸属性分析都有额外的计算和时间成本。
FaceLandmarks	27 磅人脸特征点的集合，指向人脸组件的重要位置。
FaceRectangle	可在其中找到人脸的矩形
FacialHair	描述面部头发属性的属性。
Gender	人脸的可能性别。
GlassesType	眼镜类型（如果任何人脸）。
Hair	描述头发属性的属性。
HairColor	头发颜色和相关置信度
HairColorType	头发颜色的名称。
HeadPose	指示人脸头部姿势的属性。
ImageUrl
Makeup	描述给定脸上存在化妆的属性。
Mask	描述给定人脸上存在掩码的属性。
MaskType	如果任何人脸，则掩码类型
Noise	描述图像噪音级别的属性。
NoiseLevel	指示干扰级别的枚举值。
Occlusion	描述给定人脸上遮挡的属性。
QualityForRecognition	一个枚举值，指示图像的质量以供识别。
RecognitionModel	识别模型的名称。提取人脸特征并与检测到的 faceId、（Large）FaceList 或（Large）PersonGroup 相关联时，将使用识别模型。执行人脸 - 检测或（大型）FaceList - 创建或（大型）PersonGroup - 创建时，可以提供识别模型名称。默认值为“recognition_01”，如果需要最新模型，请显式指定所需的模型。

Accessory

Object

附件项和相应的置信度。

名称	类型	说明
confidence	number minimum: 0 maximum: 1	附件的置信度
type	AccessoryType	附件的类型

AccessoryType

枚举

附件的类型

值	说明
glasses
headWear
mask

APIError

Object

API 返回的错误信息

名称	类型	说明
error	Error	错误正文。

Blur

Object

描述图像中存在模糊状态的属性。

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

BlurLevel

枚举

一个指示模糊级别的枚举值。

值	说明
High
Low
Medium

Coordinate

Object

图像中的坐标

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

DetectedFace

Object

检测到的人脸对象。

名称	类型	默认值	说明
faceAttributes	FaceAttributes		人脸属性
faceId	string (uuid)
faceLandmarks	FaceLandmarks		27 磅人脸特征点的集合，指向人脸组件的重要位置。
faceRectangle	FaceRectangle		可在其中找到人脸的矩形
recognitionModel	RecognitionModel	recognition_01	识别模型的名称。提取人脸特征并与检测到的 faceId、（Large）FaceList 或（Large）PersonGroup 相关联时，将使用识别模型。执行人脸 - 检测或（大型）FaceList - 创建或（大型）PersonGroup - 创建时，可以提供识别模型名称。默认值为“recognition_01”，如果需要最新模型，请显式指定所需的模型。

DetectionModel

枚举

检测模型的名称。检测模型用于检测提交的图像中的人脸。执行人脸 - 检测或（大型）FaceList - 添加人脸或（大型）PersonGroup - 添加人脸时，可以提供检测模型名称。默认值为“detection_01”，如果需要另一个模型，请显式指定它。

值	说明
detection_01
detection_02
detection_03

Emotion

Object

描述面部情感的属性，其置信度从 0 到 1 不等。

名称	类型	说明
anger	number minimum: 0 maximum: 1	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。
contempt	number minimum: 0 maximum: 1	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。
disgust	number minimum: 0 maximum: 1	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。
fear	number minimum: 0 maximum: 1	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。
happiness	number minimum: 0 maximum: 1	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。
neutral	number minimum: 0 maximum: 1	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。
sadness	number minimum: 0 maximum: 1	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。
surprise	number minimum: 0 maximum: 1	一个介于 0 到 1 的数字，指示与属性关联的置信度级别。

Error

Object

错误正文。

名称	类型	说明
code	string
message	string

Exposure

Object

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

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

ExposureLevel

枚举

指示曝光级别的枚举值。

值	说明
GoodExposure
OverExposure
UnderExposure

FaceAttributes

Object

人脸属性

名称	类型	说明
accessories	Accessory[]	描述给定人脸上任何配件的属性。
age	number	年龄（年）
blur	Blur	描述图像中存在模糊状态的属性。
emotion	Emotion	描述面部情感的属性，其置信度从 0 到 1 不等。
exposure	Exposure	描述图像曝光级别的属性。
facialHair	FacialHair	描述面部头发属性的属性。
gender	Gender	人脸的可能性别。
glasses	GlassesType	眼镜类型（如果任何人脸）。
hair	Hair	描述头发属性的属性。
headPose	HeadPose	指示人脸头部姿势的属性。
makeup	Makeup	描述给定脸上存在化妆的属性。
mask	Mask	描述给定人脸上存在掩码的属性。
noise	Noise	描述图像噪音级别的属性。
occlusion	Occlusion	描述给定人脸上遮挡的属性。
qualityForRecognition	QualityForRecognition	描述在检测中使用的图像的整体图像质量的属性是否具有足够的质量来尝试进行人脸识别。
smile	number minimum: 0 maximum: 1	微笑强度，介于 [0,1] 之间的数字

FaceAttributeType

枚举

分析和返回逗号分隔字符串中的一个或多个指定人脸属性，例如“returnFaceAttributes=age，gender”。可用属性取决于指定的“detectionModel”。 “detection_01”支持年龄、性别、headPose、微笑、面部海尔、眼镜、情感、头发、化妆、遮挡、配件、模糊、暴露、噪音和质量ForRecognition。虽然“detection_02”不支持任何属性，“detection_03”仅支持 mask 和 qualityForRecognition。此外，仅当“recognitionModel”指定为“recognition_03”或“recognition_04”时，才支持 qualityForRecognition。请注意，每个人脸属性分析都有额外的计算和时间成本。

值	说明
accessories
age
blur
emotion
exposure
facialHair
gender
glasses
hair
headPose
makeup
mask
noise
occlusion
qualityForRecognition
smile

FaceLandmarks

Object

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

名称	类型	说明
eyeLeftBottom	Coordinate	图像中的坐标
eyeLeftInner	Coordinate	图像中的坐标
eyeLeftOuter	Coordinate	图像中的坐标
eyeLeftTop	Coordinate	图像中的坐标
eyeRightBottom	Coordinate	图像中的坐标
eyeRightInner	Coordinate	图像中的坐标
eyeRightOuter	Coordinate	图像中的坐标
eyeRightTop	Coordinate	图像中的坐标
eyebrowLeftInner	Coordinate	图像中的坐标
eyebrowLeftOuter	Coordinate	图像中的坐标
eyebrowRightInner	Coordinate	图像中的坐标
eyebrowRightOuter	Coordinate	图像中的坐标
mouthLeft	Coordinate	图像中的坐标
mouthRight	Coordinate	图像中的坐标
noseLeftAlarOutTip	Coordinate	图像中的坐标
noseLeftAlarTop	Coordinate	图像中的坐标
noseRightAlarOutTip	Coordinate	图像中的坐标
noseRightAlarTop	Coordinate	图像中的坐标
noseRootLeft	Coordinate	图像中的坐标
noseRootRight	Coordinate	图像中的坐标
noseTip	Coordinate	图像中的坐标
pupilLeft	Coordinate	图像中的坐标
pupilRight	Coordinate	图像中的坐标
underLipBottom	Coordinate	图像中的坐标
underLipTop	Coordinate	图像中的坐标
upperLipBottom	Coordinate	图像中的坐标
upperLipTop	Coordinate	图像中的坐标

FaceRectangle

Object

可在其中找到人脸的矩形

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

FacialHair

Object

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

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

Gender

枚举

人脸的可能性别。

值	说明
female
male

GlassesType

枚举

眼镜类型（如果任何人脸）。

值	说明
noGlasses
readingGlasses
sunglasses
swimmingGoggles

Hair

Object

描述头发属性的属性。

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

HairColor

Object

头发颜色和相关置信度

名称	类型	说明
color	HairColorType	头发颜色的名称。
confidence	number minimum: 0 maximum: 1	颜色的置信度

HairColorType

枚举

头发颜色的名称。

值	说明
black
blond
brown
gray
other
red
unknown
white

HeadPose

Object

指示人脸头部姿势的属性。

名称	类型	说明
pitch	number
roll	number
yaw	number

ImageUrl

Object

名称	类型	说明
url	string	图像的可公开访问 URL

Makeup

Object

描述给定脸上存在化妆的属性。

名称	类型	说明
eyeMakeup	boolean	一个布尔值，描述人脸上是否存在眼妆。
lipMakeup	boolean	一个布尔值，描述脸上是否存在唇妆。

Mask

Object

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

名称	类型	说明
noseAndMouthCovered	boolean	一个布尔值，该值指示鼻子和嘴是否覆盖。
type	MaskType	如果任何人脸，则掩码类型

MaskType

枚举

如果任何人脸，则掩码类型

值	说明
faceMask
noMask
otherMaskOrOcclusion
uncertain

Noise

Object

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

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

NoiseLevel

枚举

指示干扰级别的枚举值。

值	说明
High
Low
Medium

Occlusion

Object

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

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

QualityForRecognition

枚举

一个枚举值，指示图像的质量以供识别。

值	说明
High
Low
Medium

RecognitionModel

枚举

识别模型的名称。提取人脸特征并与检测到的 faceId、（Large）FaceList 或（Large）PersonGroup 相关联时，将使用识别模型。执行人脸 - 检测或（大型）FaceList - 创建或（大型）PersonGroup - 创建时，可以提供识别模型名称。默认值为“recognition_01”，如果需要最新模型，请显式指定所需的模型。

值	说明
recognition_01
recognition_02
recognition_03
recognition_04

通过

Face - Detect With Url

URI 参数

请求头

请求正文

响应

安全性

Ocp-Apim-Subscription-Key

示例

Detect with url example

示例请求

示例响应

定义

Accessory

AccessoryType

APIError

Blur

BlurLevel

Coordinate

DetectedFace

DetectionModel

Emotion

Error

Exposure

ExposureLevel

FaceAttributes

FaceAttributeType

FaceLandmarks

FaceRectangle

FacialHair

Gender

GlassesType

Hair

HairColor

HairColorType

HeadPose

ImageUrl

Makeup

Mask

MaskType

Noise

NoiseLevel

Occlusion

QualityForRecognition

RecognitionModel