Face - Detect
在图片中检测人脸,并返回人脸位置信息,也可以一并返回faceIds,landmark,attributes信息.
可选参数用于返回faceId,landmark和attributes 信息. Attributes信息包括年龄,性别,微笑程度,面部毛发,头部姿势,眼镜,情感,头发,化妆,咬合,配件,模糊,曝光和噪音.
faceId 将稍后应用于其他的APIs, 包括 Face - Identity,Face - Verify, 以及 Face - Similar .faceId 将于调用检测方法以后24小时过期.
* 目前支持 JPEG,PNG,GIF(第一帧)和BMP图片格式.图片大小需要大于等于1KB且小于4MB.
* 可检测的人脸尺寸在36×36像素到 4096×4096像素 之间. 如果人脸没有在这个范围内,则无法进行检测.
* 一张图片最多只能返回64个人脸,返回的人脸将按照人脸检测矩形的大小由大到小排列.
* 一些刻意角度的人脸可能无法识别，如：超大的脸角(头部未知)或者是张大嘴。最好提供正脸或者接近正脸的图片是最好的。
* 属性(年龄、性别、头部位置、微笑、胡子、眼镜、表情、头发、妆容、咬合、配饰、污渍、曝光和干扰)仍在试验中，可能结果不是很精准。头部姿势尚未开发，并且返回值为0
Http Method
请求方式
POST
request URL
请求地址
https://api.cognitive.azure.cn/face/v1.0/detect[?returnFaceId][&returnFaceLandmarks][&returnFaceAttributes] 。
请求参数
| 参数名 |参数类型 |是否必填 |参数描述 |
| --- | --- | --- | --- |
| returnFaceId | boolean | 否 | 返回检测脸部的faceIds或者不返回，参数默认值为true |
| returnFaceLandmarks | boolean | 否 |返回检测脸部的脸部的坐标或则不返回，参数默认值为false |
| returnFaceAttributes | string |否 |可以通过returnFaceAttributes='age,grender'逗号相隔的字符串格式让其分析并返回指定面部属性。支持的面部属性：年龄、性别、头部位置、微笑、胡子、眼镜、表情、头发、妆容、咬合、配饰、污渍、曝光和干扰。注意的是每个面部属性分析需要时间额外计算。 |
Request headers
| 头部数据 |类型 |描述 |
| --- | --- | --- |
| Content-Type | string | 发送给Detect的主体的媒体格式 (可选) |
| Ocp-Apim-Subscription-Key | string | 在Cognitive Services accounts.中获取连接Detect Api的Subscription key |
Request body
To detect in a URL (or binary data) specified image.
将图片url(或二进制)方式进行验证
JSON fields in the request body:
json格式的请求体
Fields Type Description
url String URL of input image.
application/json
~~~
{
"url":"http://example.com/1.jpg"
}
~~~
application/octet-stream
`[binary data]`
Response 200
成功调用后返回按脸部矩形大小降序排列的脸部条目数组。空的响应表示没有检测到脸部。根据输入参数，脸部输入可能包含以下值：
| 参数名 |参数类型 |参数描述 |
| --- | --- | --- |
| faceId | String | 检测到的面部唯一faceId，由检测API创建，检测后24小时后过期。为了返回这个faceId，需要“returnFaceId”参数为true。 |
| faceRectangle | Object | 图像上的脸部矩形区域。 |
| faceLandmarks | faceLandmarks | 返回一个27点脸部特征的数组，需要“returnFaceLandmarks”参数为true。 |
| faceAttributes | Object | 年龄,gender(male or female),smile（微笑强度：[0-1]）、facialHair(面部胡须的三个特征)、headPose(头部姿势：三维头部姿势（滚动、俯仰、偏转），间距值是一个保留字段，将始终返回0)、glasses(眼镜：眼镜类型。可能的值包括“NoGlasses”)、emotion(脸上表达的情绪强度，包括anger，contempt, disgust, fear, happiness, neutral, sadness 和 surprise)、hair(指示是否有返回的头发特征，还包括头发颜色)、makeup(脸部区域（眼睛，嘴唇）是否化妆)、accessory(部或周围的饰品，包括头饰，眼镜和面具。空阵列意味着没有检测到饰品)、occlusion(脸部区域（前额，眼睛，嘴巴）是否被遮挡)、blur(脸部的模糊程度。等级包括“low”，“medium”和“high”。值越大表明脸部模糊越高) exposure(脸部的曝光水平。该级别包括“GoodExposure”，“OverExposure”和“UnderExposure)、noise(脸部干扰等级。等级包括“低”，“中”和“高”。值越大证明面部受干扰程度越高)|
~~~
[
{
"faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
"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.0,
"y": 80.1
},
"eyeLeftInner": {
"x": 418.9,
"y": 78.0
},
"eyebrowRightInner": {
"x": 4.8,
"y": 69.7
},
"eyebrowRightOuter": {
"x": 5.5,
"y": 68.5
},
"eyeRightInner": {
"x": 441.5,
"y": 75.0
},
"eyeRightTop": {
"x": 446.4,
"y": 71.7
},
"eyeRightBottom": {
"x": 447.0,
"y": 75.3
},
"eyeRightOuter": {
"x": 451.7,
"y": 73.4
},
"noseRootLeft": {
"x": 428.0,
"y": 77.1
},
"noseRootRight": {
"x": 435.8,
"y": 75.6
},
"noseLeftAlarTop": {
"x": 428.3,
"y": 89.7
},
"noseRightAlarTop": {
"x": 442.2,
"y": 87.0
},
"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.0,
"gender": "male",
"smile": 0.88,
"facialHair": {
"moustache": 0.8,
"beard": 0.1,
"sideburns": 0.02
}
},
"glasses": "sunglasses",
"headPose": {
"roll": 2.1,
"yaw": 3,
"pitch": 0
},
"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.0,
"invisible": false,
"hairColor": [
{"color": "brown", "confidence": 1.0},
{"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.0},
{"type": "mask"," confidence": 0.87}
],
"blur": {
"blurLevel":"Medium",
"value":0.51
},
"exposure": {
"exposureLevel":"GoodExposure",
"value":0.55
},
"noise": {
"noiseLevel":"Low",
"value":0.12
}
}
}
]
~~~
Response 400
Error code and message returned in JSON:
| 错误代码|错误信息描述 |
| --- | --- |
| BadArgument | JSON parsing error. Bad or unrecognizable request JSON body.JSON解析错误。请求JSON正文无效或无法识别|
| BadArgument | Invalid returnFaceAttributes. Supported values are: age, gender, headPose, smile, facialHair, glasses in a comma-separated format.无效的returnFaceAttributes。支持的值包括：以逗号分隔的年龄，性别，头像，微笑，面部发型，眼镜。 |
| InvalidURL | Invalid image format or URL. Supported formats include JPEG, PNG, GIF(the first frame) and BMP.无效的图片格式或网址。支持的格式包括JPEG，PNG，GIF（第一帧）和BMP。
|
| InvalidImage | Decoding error, image format unsupported.解码错误，图片格式不受支持
|
| InvalidImageSize | Image size is too small or too big. The valid image file size should be larger than or equal to 1KB but no larger than 4MB.图像尺寸太小或太大。有效的图像文件大小应该大于或等于1KB但不大于4MB。 |
|InvalidURL | Failed to download image from the specified URL. Remote server error returned.远程服务器错误返回，无法从指定的网址下载图片 |
~~~
{
"error":{
"code":"BadArgument",
"message":"Request body is invalid."
}
}
~~~
Response 401
Error code and message returned in JSON:
| 错误代码|错误描述 |
| --- | --- |
| Unspecified | Invalid subscription Key or user/plan is blocked(无效的subscription Key或user/plan被锁) |
~~~
{
"error":{
"code": "Unspecified",
"message": "Access denied due to invalid subscription key. Make sure you are subscribed to an API you are trying to call and provide the right key." (因为无效的subscription key链接失败，请确定已订阅该API并提供正确的subscription key)
}
}
~~~
Response 403
容量不足
~~~
{
"error":{
"statusCode": 403,
"message": "Out of call volume quota. Quota will be replenished in 2.12 days."
}
}
~~~
返回值408
计算超时
~~~
{
"error":{
"code":"OperationTimeOut",
"message":"Request Timeout."
}
}
~~~
Response 415
不支持的媒体类型错误。Content-Type不在允许的类型中：
1. 对于图片网址，Content-Type应该是application / json
2. 对于本地图像，Content-Type应该是application / octet-stream
~~~
{
"error":{
"code":"BadArgument",
"message":"Invalid Media Type"
}
}
~~~
Response 429
操作过于频繁
~~~
{
"error":{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in 26 seconds."
}
}
~~~
- 空白目录
- Face
- Detect
- Find Similar
- Group
- Identify
- Verify
- Face List
- Add a Face to a Face List
- Create a Face List
- Delete a Face from a Face List
- Delete a Face List
- Get a Face List
- List Face Lists
- Update a Face List
- Person
- Add a Person Face
- Create a Person
- Delete a Person
- Delete a Person Face
- Get a Person
- Get a Person Face
- List Persons in a Person Group
- Update a Person
- Update a Person Face
- Person Group
- Create a Person Group
- Delete a Person Group
- Get a Person Group
- Get Person Group Training Status
- List Person Groups
- Train Person Group
- Update a Person Group