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." } } ~~~