人臉屬性檢測增強(qiáng)版
本文介紹調(diào)用人臉屬性檢測API進(jìn)行圖片中人臉及人臉屬性檢測的方法。
一、功能介紹
人臉屬性檢測能夠識(shí)別圖片中的人臉屬性信息，包括人臉模糊度、人臉角度、人臉位置、微笑程度、是否戴眼鏡、是否戴口罩、是否戴帽子、是否有胡子、是否有劉海、頭發(fā)類型等。
服務(wù)（Service） | 檢測說明 |
服務(wù)名：人臉屬性檢測 Service：faceDetect |
|
二、計(jì)費(fèi)說明
圖片人臉屬性檢測增強(qiáng)版支持按量后付費(fèi)和資源包抵扣兩種付費(fèi)方式。
按量后付費(fèi)
當(dāng)您開通內(nèi)容安全增強(qiáng)版服務(wù)后，默認(rèn)付費(fèi)方式是按量后付費(fèi)，且按照實(shí)際用量結(jié)算當(dāng)日費(fèi)用，不調(diào)用服務(wù)不收費(fèi)。
審核類型 | 支持的業(yè)務(wù)場景（服務(wù)） | 計(jì)費(fèi)單價(jià) |
圖片識(shí)別通用（image_standard） |
| 15元/萬次 說明 調(diào)用1次左側(cè)任一服務(wù)進(jìn)行1次計(jì)費(fèi)。根據(jù)實(shí)際調(diào)用量計(jì)費(fèi)，如調(diào)用100次人臉屬性檢測計(jì)費(fèi)0.15元。 |
內(nèi)容安全增強(qiáng)版的按量付費(fèi)的計(jì)量出賬頻率為1小時(shí)/次。在出賬詳單中，moderationType對應(yīng)上述審核類型字段。您可以查看賬單詳情。
資源包抵扣
如果您的識(shí)別量較大，或有相對固定的識(shí)別需求，建議預(yù)先購買資源包的方式。購買資源包規(guī)格越大，享受的折扣越大，支持疊加購買和使用。更多內(nèi)容，請參見購買內(nèi)容審核增強(qiáng)版抵扣資源包。
該資源包用于內(nèi)容安全增強(qiáng)版用量的抵扣，無法與內(nèi)容安全1.0版流量包共享，具體的抵扣系數(shù)如下：
審核類型 | 支持的業(yè)務(wù)場景（服務(wù)） | 抵扣系數(shù) |
圖片識(shí)別通用（image_standard） |
| 2：即每成功調(diào)用一次接口，抵扣資源包的流量包容量規(guī)格2次。 例如購買的資源包的流量包容量規(guī)格為10次，當(dāng)您成功調(diào)用1次接口，抵扣流量包容量規(guī)格2次，剩余8次。 |
購買后，使用圖片識(shí)別增強(qiáng)版API所產(chǎn)生的用量會(huì)優(yōu)先抵扣資源包的次數(shù)，當(dāng)資源包次數(shù)不足以抵扣時(shí)，阿里云費(fèi)用系統(tǒng)會(huì)自動(dòng)按照按量付費(fèi)進(jìn)行出賬，請及時(shí)關(guān)注您的資源包余量和按量付費(fèi)賬單。您可以通過阿里云費(fèi)用中心的資源包系統(tǒng)設(shè)定余量預(yù)警通知。
三、接入指引
注冊阿里云賬號(hào)：立即注冊，按照操作提示完成賬號(hào)注冊。
開通內(nèi)容安全按量付費(fèi)：請確保您已開通服務(wù)，開通不收費(fèi)，接口接入使用后系統(tǒng)會(huì)按使用量自動(dòng)出賬，詳情請參見計(jì)費(fèi)說明。您也可以購買按量抵扣資源包，資源包相較于后付費(fèi)存在一定階梯抵扣，適合使用量級(jí)可預(yù)期和較大的用戶。
創(chuàng)建AccessKey：請確保您已通過RAM創(chuàng)建AccessKey，如果您使用的是子賬號(hào)AccessKey，您需要通過主賬號(hào)給子賬號(hào)賦予AliyunYundunGreenWebFullAccess權(quán)限，具體操作，請參見RAM授權(quán)。
開發(fā)接入：推薦使用SDK方式調(diào)用，具體方法請?jiān)斠?a href="http://bestwisewords.com/document_detail/467828.html#task-2275871" id="bdacbcf319ocs" title="" class="xref">圖片審核增強(qiáng)版SDK及接入指南。
四、API接口
使用說明
您可以調(diào)用該接口創(chuàng)建圖片內(nèi)容檢測任務(wù)。關(guān)于如何構(gòu)造HTTP請求，請參見接入指南；您也可以直接選用已構(gòu)造好的HTTP請求，更多信息，請參見SDK參考。
業(yè)務(wù)接口：ImageModeration
支持的地域及接入地址：
地域 | 外網(wǎng)接入地址 | 內(nèi)網(wǎng)接入地址 | 支持服務(wù) |
華東2（上海） | https://green-cip.cn-shanghai.aliyuncs.com | https://green-cip-vpc.cn-shanghai.aliyuncs.com | faceDetect |
華東1（杭州） | https://green-cip.cn-hangzhou.aliyuncs.com | https://green-cip-vpc.cn-hangzhou.aliyuncs.com |
計(jì)費(fèi)信息：該接口為收費(fèi)接口。僅對HTTP狀態(tài)碼為200的請求進(jìn)行計(jì)量計(jì)費(fèi)，產(chǎn)生其他錯(cuò)誤碼時(shí)不會(huì)計(jì)費(fèi)。關(guān)于計(jì)費(fèi)方式，請參見計(jì)費(fèi)說明。
圖片要求：
圖片支持以下格式：PNG、JPG、JPEG、BMP、WEBP、TIFF、SVG、HEIC（該格式最長邊需小于8192 px）、GIF（取第一幀）、ICO（取最后一圖）。
圖片大小限制在20 MB以內(nèi)，高或者寬不能超過16,384 px，且總像素不能超過1.67億 px。像素建議大于200*200（px），像素過低會(huì)影響內(nèi)容安全檢測算法的效果。
圖片下載時(shí)間限制為3秒內(nèi)，如果下載時(shí)間超過3秒，返回下載超時(shí)。
QPS限制
本接口的單用戶QPS限制為10次/秒。超過限制，API調(diào)用會(huì)被限流，這可能會(huì)影響您的業(yè)務(wù)，請合理調(diào)用。如果您業(yè)務(wù)量級(jí)較大或者有緊急擴(kuò)容需求需要更大QPS，請聯(lián)系您的商務(wù)經(jīng)理。
調(diào)試
在接入前，您也可以通過阿里云OpenAPI在線調(diào)試圖片審核增強(qiáng)版的接口，查看調(diào)用示例代碼及SDK依賴信息，方便概覽接口的使用方法和參數(shù)。
在線調(diào)試能力是基于當(dāng)前登錄賬號(hào)調(diào)用內(nèi)容安全的API接口，因此調(diào)用量會(huì)計(jì)入賬號(hào)的收費(fèi)用量中。
請求參數(shù)
關(guān)于在請求中必須包含的公共請求參數(shù)，請參考圖片審核增強(qiáng)版SDK及接入指南。
請求body是一個(gè)JSON結(jié)構(gòu)體，包含以下字段：
名稱 | 類型 | 是否必選 | 示例值 | 描述 |
Service | String | 是 | faceDetect | 圖片檢測增強(qiáng)版支持的檢測服務(wù)。取值：
|
ServiceParameters | JSONString | 是 | 內(nèi)容檢測對象的相關(guān)參數(shù)集。JSON字符串格式，關(guān)于每個(gè)字符串的描述，請參見ServiceParameters。 |
表 1. ServiceParameters
名稱 | 類型 | 是否必選 | 示例值 | 描述 |
imageUrl | String | 是。圖片識(shí)別增強(qiáng)版支持三種方式傳入圖片，請您選擇其中一種：
| https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png | 待檢測對象的URL，請確保該URL能通過公網(wǎng)訪問到，且URL地址長度不超過2048個(gè)字符。 說明 URL地址中不能包含中文，且一次請求請確保僅傳入1條URL。 |
ossBucketName | String | bucket_01 | 已授權(quán)OSS空間的Bucket名。 說明 使用OSS圖片內(nèi)網(wǎng)地址時(shí)必須先使用阿里云賬號(hào)（即主賬號(hào)）訪問云資源訪問授權(quán)頁面進(jìn)行授權(quán)。 | |
ossObjectName | String | 20240307/04/24/test.jpg | 已授權(quán)OSS空間的文件名。 | |
ossRegionId | String | cn-beijing | OSS Bucket所在區(qū)域。 | |
dataId | String | 否 | img123**** | 檢測對象對應(yīng)的數(shù)據(jù)ID。 由大小寫英文字母、數(shù)字、下劃線（_）、短劃線（-）、英文句號(hào)（.）組成，不超過64個(gè)字符，可以用于唯一標(biāo)識(shí)您的業(yè)務(wù)數(shù)據(jù)。 |
referer | String | 否 | www.aliyun.com | referer請求頭，用于防盜鏈等場景。長度不超過256個(gè)字符。 |
返回?cái)?shù)據(jù)
名稱 | 類型 | 示例值 | 描述 |
RequestId | String | 70ED13B0-BC22-576D-9CCF-1CC12FEAC477 | 本次調(diào)用請求的ID，是由阿里云為該請求生成的唯一標(biāo)識(shí)符，可用于排查和定位問題。 |
Data | Object | 圖片內(nèi)容檢測結(jié)果。更多信息，請參見Data。 | |
Code | Integer | 200 | 狀態(tài)碼。更多信息，請參見Code說明。 |
Msg | String | OK | 本次請求的響應(yīng)消息。 |
表 2. Data
名稱 | 類型 | 示例值 | 描述 |
Ext | Object | 人臉屬性檢測結(jié)果。更多信息，請參見Ext。 | |
DataId | String | img123****** | 檢測對象對應(yīng)的數(shù)據(jù)ID。 說明 如果在檢測請求參數(shù)中傳入了dataId，則此處返回對應(yīng)的dataId。 |
Result | Array | 圖片審核的風(fēng)險(xiǎn)標(biāo)簽、置信分等參數(shù)結(jié)果。更多信息，請參見Result。 說明 使用人臉屬性檢測時(shí)，該返回值暫時(shí)可以忽略。 |
表 3. Ext
名稱 | 類型 | 示例值 | 描述 |
FaceData | Array | 人臉屬性檢測結(jié)果。更多信息，請參見FaceData。 |
表 4. FaceData
名稱 | 類型 | 示例值 | 描述 |
Location | JSONObject | 人臉位置信息，具體結(jié)構(gòu)描述，請參見Location。 | |
Smile | Float | 85.88 | 人臉的微笑程度。取值范圍：0~100。分?jǐn)?shù)越高表示微笑程度越大。 |
Glasses | String | None | 是否佩戴眼鏡的識(shí)別結(jié)果，取值：
|
Age | Integer | 18 | 年齡識(shí)別結(jié)果。 |
Quality | JSONObject | 人臉圖片的質(zhì)量信息，具體結(jié)構(gòu)描述，請參見Quality。 | |
Mask | JSONObject | 是否佩戴口罩的識(shí)別結(jié)果，具體結(jié)構(gòu)描述，請參見Mask。 | |
Hat | JSONObject | 是否佩戴帽子的識(shí)別結(jié)果，具體結(jié)構(gòu)描述，請參見Hat。 | |
Mustache | JSONObject | 是否有胡子的識(shí)別結(jié)果，具體結(jié)構(gòu)描述，請參見Mustache。 | |
Bang | JSONObject | 是否有劉海的識(shí)別結(jié)果，具體結(jié)構(gòu)描述，請參見Bang。 | |
Hairstyle | JSONObject | 發(fā)型識(shí)別結(jié)果，具體結(jié)構(gòu)描述，請參見Hairstyle。 | |
Gender | JSONObject | 性別識(shí)別結(jié)果，具體結(jié)構(gòu)描述，請參見Gender。 |
表 5.Location
名稱 | 類型 | 示例值 | 描述 |
X | Float | 41 | 以圖片左上角為坐標(biāo)原點(diǎn)，人臉區(qū)域左上角到y(tǒng)軸的距離，單位：像素。 |
Y | Float | 84 | 以圖片左上角為坐標(biāo)原點(diǎn)，人臉區(qū)域左上角到x軸的距離，單位：像素。 |
W | Float | 83 | 人臉區(qū)域的寬度，單位：像素。 |
H | Float | 26 | 人臉區(qū)域的高度，單位：像素。 |
表 6.Quality
名稱 | 類型 | 示例值 | 描述 |
Blur | Float | 5.88 | 人臉圖片的模糊度，取值范圍：0~100。分?jǐn)?shù)越高表示越模糊。 建議取值范圍：0~25。 |
Integrity | Float | 100.0 | 人臉的完整度，取值范圍：0~100。分?jǐn)?shù)越高表示越完整。 建議取值范圍：80~100。 |
Pitch | Float | 5.88 | 人臉的抬頭或低頭角度。 建議取值范圍：-30~30。 |
Yaw | Float | 5.18 | 人臉的左右搖頭角度。 建議取值范圍：-30~30。 |
Roll | Float | 5.18 | 人臉的平面旋轉(zhuǎn)角度。 建議取值范圍：-30~30。 |
表 7.Mask
名稱 | 類型 | 示例值 | 描述 |
Value | String | None | 是否佩戴口罩的識(shí)別結(jié)果，取值：
|
Confidence | Float | 99.99 | 佩戴口罩結(jié)果的置信度，取值范圍：0~100。取值越高表示結(jié)果越可信。 |
表 8.Hat
名稱 | 類型 | 示例值 | 描述 |
Value | String | Wear | 是否佩戴帽子的識(shí)別結(jié)果，取值：
|
Confidence | Float | 88.88 | 佩戴帽子結(jié)果的置信度，取值范圍：0~100。取值越高表示結(jié)果越可信。 |
表 9.Mustache
名稱 | 類型 | 示例值 | 描述 |
Value | String | None | 是否有胡須的識(shí)別結(jié)果，取值：
|
Confidence | Float | 99.99 | 胡須識(shí)別結(jié)果的置信度，取值范圍：0~100。取值越高表示結(jié)果越可信。 |
表 10.Bang
名稱 | 類型 | 示例值 | 描述 |
Value | String | None | 是否有劉海的識(shí)別結(jié)果，取值：
|
Confidence | Float | 81.88 | 劉海識(shí)別結(jié)果的置信度，取值范圍：0~100。取值越高表示結(jié)果越可信。 |
表 11.Hairstyle
名稱 | 類型 | 示例值 | 描述 |
Value | String | Short | 發(fā)型識(shí)別結(jié)果，取值：
|
Confidence | Float | 81.88 | 發(fā)型識(shí)別結(jié)果的置信度，取值范圍：0~100。取值越高表示結(jié)果越可信。 |
表 12.Gender
名稱 | 類型 | 示例值 | 描述 |
Value | String | Male | 性別識(shí)別結(jié)果，取值：
|
Confidence | Float | 81.88 | 性別識(shí)別結(jié)果的置信度，取值范圍：0~100。取值越高表示結(jié)果越可信。 |
表 13. Result
名稱 | 類型 | 示例值 | 描述 |
Label | String | nonLabel | 圖片檢測運(yùn)算后返回的標(biāo)簽。人臉屬性檢測場景默認(rèn)返回nonLabel，無需處理該標(biāo)簽。 |
Confidence | Float | 99.99 | 置信分值，0到100分，保留到小數(shù)點(diǎn)后2位。返回nonLabel時(shí)無置信分。 |
示例
請求示例
{
"Service": "faceDetect",
"ServiceParameters": {
"imageUrl": "https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png",
"dataId": "test0307****"
}
}返回示例
{
"Code": 200,
"Data": {
"DataId": "test0307****",
"Ext": {
"FaceData": [
{
"Age": 24,
"Bang": {
"Confidence": 100.0,
"Value": "None"
},
"Gender": {
"Confidence": 95.72,
"Value": "Male"
},
"Glasses": "None",
"Hairstyle": {
"Confidence": 98.23,
"Value": "Short"
},
"Hat": {
"Confidence": 99.99,
"Value": "None"
},
"Location": {
"H": 98,
"W": 98,
"X": 550,
"Y": 251
},
"Mask": {
"Confidence": 99.99,
"Value": "None"
},
"Mustache": {
"Confidence": 99.58,
"Value": "None"
},
"Quality": {
"Blur": 13.72,
"Integrity": 100.0,
"Pitch": 5.84,
"Roll": 3.66,
"Yaw": 21.22
},
"Smile": 82.49
}
]
},
"Result": [
{
"Confidence": null,
"Description": "未檢測出風(fēng)險(xiǎn)",
"Label": "nonLabel"
}
],
"RiskLevel": "none"
},
"Msg": "success",
"RequestId": "TEST001-2024-0307-0728-5201314YHX"
}文檔中的請求示例和返回示例為了便于閱讀，做了格式化處理，實(shí)際返回結(jié)果是沒有進(jìn)行換行、縮進(jìn)等處理。
Code說明
以下為接口返回code的含義說明，系統(tǒng)僅對code返回為200的請求計(jì)量計(jì)費(fèi)，其他code不會(huì)計(jì)費(fèi)。
Code | 說明 |
200 | 請求正常。 |
400 | 請求參數(shù)為空。 |
401 | 請求參數(shù)錯(cuò)誤。 |
402 | 請求參數(shù)長度不符合接口規(guī)定，請檢查并修改。 |
403 | 請求超過QPS限制，請檢查并調(diào)整并發(fā)。 |
404 | 傳入的圖片下載遇到錯(cuò)誤，請檢查或重試。 |
405 | 傳入的圖片下載超時(shí)，可能是因?yàn)閳D片無法訪問，請檢查調(diào)整后重試。 |
406 | 傳入的圖片過大，請檢查調(diào)整圖片大小后再重試。 |
407 | 傳入的圖片格式暫不支持，請檢查調(diào)整后重試。 |
408 | 該賬號(hào)無權(quán)限調(diào)用該接口，可能是賬號(hào)未開通或者已欠費(fèi)，或者調(diào)用賬號(hào)未被授權(quán)訪問。 |
500 | 系統(tǒng)異常。 |