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