使用人臉屬性檢測API識別圖片中的人臉資訊-Alibaba Content Security Service-阿里雲

本文介紹了調用人臉屬性檢測介面（/green/face/detect）進行圖片人臉屬性檢測的方法。人臉屬性檢測能夠識別圖片中的人臉屬性資訊，包括人臉模糊度、人臉角度、人臉位置、微笑程度、是否戴眼鏡、是否戴口罩、是否戴帽子、是否有鬍子、是否有劉海、頭髮類型等。

使用說明

業務介面：/green/face/detect，表示人臉屬性同步檢測。

您可以調用該介面建立人臉屬性檢測任務並直接獲得檢測結果。關於如何構造HTTP請求，請參見請求結構；您也可以直接選用已構造好的HTTP請求，更多資訊，請參見SDK概覽。

計費資訊：
該介面為收費介面。關於計費方式，請參見Alibaba Content Security Service產品定價。
檢測逾時：
同步檢測允許的最長檢測時間是6秒，如果檢測在該時間限制內沒有完成，系統會強制返回逾時錯誤碼。如果您對即時性要求不高，可以選擇非同步檢測，其他情況下請選擇同步檢測，同步檢測介面的調用相對簡單些。對於同步檢測介面的調用，建議您將逾時時間設定為6秒。
返回結果：
同步檢測請求一般會在一秒內同步返回結果，但在一些特殊情境（例如系統繁忙導致堆積嚴重、圖片較大、含有OCR內容較多等），耗時可能會增加。
圖片要求：
- 圖片連結支援以下協議：HTTP和HTTPS。
- 圖片支援以下格式：PNG、JPG、JPEG、BMP、GIF、WEBP。
- 圖片大小限制為20 MB以內（適用於同步和非同步呼叫）。
- 圖片下載時間限制為3秒內，如果下載時間超過3秒，返回下載逾時。
- 圖片像素建議不低於256*256（px），像素過低可能會影響識別效果。
- 圖片檢測介面的回應時間依賴圖片的下載時間。請保證被檢測圖片所在的儲存服務穩定可靠，建議您使用阿里雲OSS儲存或者CDN緩衝等。

QPS限制

本介面的單使用者QPS限制為50次/秒。超過限制，API調用會被限流，這可能會影響您的業務，請合理調用。

請求參數

名稱	類型	是否必選	描述
bizType	String	否	該欄位用於標識您的業務情境。您可以通過Alibaba Content Security Service控制台建立業務情境（具體操作，請參見自訂機審標準）。
dataId	String	否	待檢測圖片的資料ID。如果該值不為空白則會在響應中返回，您可以根據該值區分不同的圖片。
url	String	是	待檢測圖片的URL。

返回資料

名稱	類型	描述
code	String	錯誤碼，和HTTP狀態代碼一致。
msg	String	錯誤描述資訊。
dataId	String	檢測對象對應的資料ID。說明如果在檢測請求參數中傳入了dataId，則此處返回對應的dataId。
taskId	String	檢測任務的ID。
url	String	公網HTTP/HTTPS URL，且長度不超過2048個字元。
faces	JSONArray	調用成功時（code為200），返回的人臉屬性資訊，每個數組元素對應一張人臉。關於每個元素的結構描述，請參見face。

表 1. face
名稱	類型	描述
location	JSONObject	人臉位置資訊，具體結構描述，請參見location。
smile	JSONObject	人臉的微笑程度，具體結構描述，請參見smile。
glasses	JSONObject	是否佩戴眼鏡的識別結果，具體結構描述，請參見glasses。
quality	JSONObject	人臉圖片的品質資訊，具體結構描述，請參見quality。
qualified	Boolean	人臉圖片品質是否合格，取值： true：合格。 false：不合格。針對圖片中檢測到的每個人臉，Alibaba Content Security Service會判斷人臉圖片品質是否合格。合格的人臉圖片必須同時滿足以下條件：人臉模糊度小於5。未佩戴墨鏡。人臉角度（包括人臉左右搖頭角度、人臉抬頭低頭角度、人臉平面旋轉角度）在30度以內。您可以根據返回的人臉屬性值控制人臉圖片品質，用作人臉底庫品質管理等情境。
respirator	JSONObject	是否佩戴口罩的識別結果，具體結構描述，請參見respirator。
hat	JSONObject	是否佩戴帽子的識別結果，具體結構描述，請參見hat。
mustache	JSONObject	是否有鬍子的識別結果，具體結構描述，請參見mustache。
bang	JSONObject	是否有劉海的識別結果，具體結構描述，請參見bang。
hairstyle	JSONObject	髮型識別結果，具體結構描述，請參見hairstyle。

表 2. location
名稱	類型	描述
x	Float	以圖片左上方為座標原點，人臉地區左上方到y軸的距離，單位：像素。
y	Float	以圖片左上方為座標原點，人臉地區左上方到x軸的距離，單位：像素。
w	Float	人臉地區的寬度，單位：像素。
h	Float	人臉地區的高度，單位：像素。

表 3. smile
名稱	類型	描述
value	Float	人臉的微笑程度。取值範圍：0~1。分數越高表示微笑程度越大。
rate	Float	微笑結果的信賴度，取值範圍：0~1。取值越高表示結果越可信。

表 4. glasses
名稱	類型	描述
value	String	是否佩戴眼鏡的識別結果，取值： None：未佩戴眼鏡。 Wear：佩戴眼鏡。 Sunglass：佩戴墨鏡。
rate	Float	佩戴眼鏡結果的信賴度，取值範圍：0~1。取值越高表示結果越可信。

表 5. quality
名稱	類型	描述
blur	Float	人臉圖片的模糊度，取值範圍：0~20。分數越高表示越模糊。建議取值範圍：0~5。
pitch	Float	人臉的抬頭或低頭角度。建議取值範圍：-30~30。
yaw	Float	人臉的左右搖頭角度。建議取值範圍：-30~30。
roll	Float	人臉的平面旋轉角度。建議取值範圍：-30~30。

表 6. respirator
名稱	類型	描述
value	String	是否佩戴口罩的識別結果，取值： Wear：佩戴口罩。 None：未佩戴口罩。
rate	Float	佩戴口罩結果的信賴度，取值範圍：0~1。取值越高表示結果越可信。

表 7. hat
名稱	類型	描述
value	String	是否佩戴帽子的識別結果，取值： Wear：佩戴帽子。 None：未佩戴帽子。
rate	Float	佩戴帽子結果的信賴度，取值範圍：0~1。取值越高表示結果越可信。

表 8. mustache
名稱	類型	描述
value	String	是否有鬍鬚的識別結果，取值： Has：有鬍鬚。 None：無鬍鬚。
rate	Float	鬍鬚識別結果的信賴度，取值範圍：0~1。取值越高表示結果越可信。

表 9. bang
名稱	類型	描述
value	String	是否有劉海的識別結果，取值： Has：有劉海。 None：無劉海。
rate	Float	劉海識別結果的信賴度，取值範圍：0~1。取值越高表示結果越可信。

表 10. hairstyle
名稱	類型	描述
value	String	髮型識別結果，取值： Bald：光頭。 Long：長發。 Short：短髮。
rate	Float	髮型識別結果的信賴度，取值範圍：0~1。取值越高表示結果越可信。

樣本

請求樣本

http(s)://[Endpoint]/green/face/detect
&<公用請求參數>
{
    "bizType": "abc",
    "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
    "url": "http://example.com/face1.jpeg"
}

正常返回樣本

{
    "msg": "OK",
    "code": 200,
    "extras": {
        "width": "328",
        "height": "390"
    },
    "faces": [
        {
            "glasses": {
                "rate": 0.99,
                "value": "None"
            },
            "qualified": false,
            "bang": {
                "rate": 0.99,
                "value": "Has"
            },
            "respirator": {
                "rate": 0.99,
                "value": "None"
            },
            "hat": {
                "rate": 0.99,
                "value": "None"
            },
            "location": {
                "w": 116,
                "h": 116,
                "x": 134,
                "y": 135
            },
            "mustache": {
                "rate": 0.99,
                "value": "None"
            },
            "hairstyle": {
                "rate": 0.99,
                "value": "Short"
            },
            "quality": {
                "roll": 0.38,
                "blur": 6.44,
                "pitch": 21.21,
                "yaw": 21.12
            },
            "smile": {
                "rate": 0.99,
                "value": 0.5
            }
        }
    ],
    "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
    "taskId": "img1uJtIrlwH$F4FA3h$Sxe2F-1tbWWx",
    "url": "http://example.com/face1.jpeg"
}