本文提供了調用圖片同步檢測任務進行人臉1:1比對的具體接口和參數說明,旨在幫助您編寫程序構建HTTP調用請求。
使用說明
業務接口:/green/image/scan
提交圖片同步檢測任務,進行人臉照片1:1比對,檢測兩張人臉照片的相似度。關于如何構造HTTP請求,請參見請求結構;您也可以直接選用已構造好的HTTP請求,更多信息,請參見SDK概覽。
計費信息:
該接口為收費接口。關于計費方式,請參見內容安全產品定價。
說明對于人臉比對功能,傳入兩張圖片進行一次比對進行一次計費(而不是兩次)。
檢測超時:
同步檢測允許的最長檢測時間是6秒,如果檢測在該時間限制內沒有完成,系統會強制返回超時錯誤碼。如果您對實時性要求不高,可以選擇異步檢測;其它情況下,請選擇同步檢測,同步檢測接口的調用相對簡單些。對于同步檢測接口的調用,建議您將超時時間設置為6秒。
圖片要求:
圖片鏈接支持以下協議:HTTP和HTTPS。
圖片支持以下格式:PNG、JPG、JPEG、BMP、GIF、WEBP。
圖片大小限制為20 MB以內(適用于同步和異步調用),高度或者寬度不能超過30,000像素(px),且圖像總像素不超過2.5億(px)。
說明其中,GIF格式的圖片,圖像總像素不超過4,194,304(px),高度或者寬度不能超過30,000像素(px)。
圖片下載時間限制為3秒內,如果下載時間超過3秒,返回下載超時。
圖片像素建議不低于256*256(px),像素過低可能會影響識別效果。
圖片檢測接口的響應時間依賴圖片的下載時間。請保證被檢測圖片所在的存儲服務穩定可靠,建議您使用阿里云OSS存儲或者CDN緩存等。
QPS限制
本接口的單用戶QPS限制為50次/秒。超過限制,API調用會被限流,這可能會影響您的業務,請合理調用。
請求參數
關于在請求中必須包含的公共請求參數,請參見公共參數。
請求body是一個JSON對象,字段說明如下:
名稱 | 類型 | 是否必選 | 示例值 | 描述 |
bizType | String | 否 | default | |
scenes | StringArray | 是 | ["sface-1"] | 指定圖片檢測的應用場景,取值:sface-1。 |
tasks | JSONArray | 是 | 指定檢測對象,JSON數組中的每個元素是一個檢測任務結構體。最多支持100個元素,即每次提交100條內容進行檢測,支持100個元素的前提是需要將并發任務調整到100個以上。關于每個元素的具體結構描述,請參見task。 |
名稱 | 類型 | 是否必選 | 示例值 | 描述 |
dataId | String | 否 | e6b080a8-a91a-11e8-bac4-6c96cfde2af9 | 數據ID。需要保證在一次請求中所有的ID不重復。 |
url | String | 是 | http://www.aliyundoc.com/2015/0826/2015082612403321.jpg | 檢測對象的URL。
說明 傳入待比較圖片中的第一張圖片的URL。 |
extras | Map | 否 | xxx | 傳入待比較圖片中的第二張圖片。格式為 |
返回數據
返回結果說明,請參見返回結果。
返回body中的data字段是JSON數組,每一個元素包含如下字段:
名稱 | 類型 | 示例值 | 描述 |
code | Integer | 200 | 錯誤碼,和HTTP狀態碼一致。 更多信息,請參見公共錯誤碼。 |
msg | String | OK | 請求信息的響應消息。 |
dataId | String | e6b080a8-a91a-11e8-bac4-6c96cfde2af9 | 對應請求中的dataId。 |
taskId | String | img2hsbmQeA4CU7l78$s8q5mW-1pnn7Z | 該檢測任務的ID。 |
url | String | http://www.aliyundoc.com/2015/0826/2015082612403321.jpg | 檢測對象的URL。
說明 對應請求中的URL,即第一張圖片的URL。 |
extras | Map | xxx | 額外調用參數。 說明 該參數可能會被調整,目前請勿依賴該參數的返回值。 |
results | JSONArray | 否 | 返回結果。調用成功時(code=200),返回結果中包含一個或多個元素。每個元素是個結構體,具體結構描述見result。 |
名稱 | 類型 | 示例值 | 描述 |
scene | String | sface-1 | 風險場景,取值:sface-1。 |
label | String | sface-1 | 檢測結果的分類,取值:
|
suggestion | String | review | 建議用戶執行的操作,取值范圍:
|
rate | Float | 97.0 | 結果為該分類的概率,取值范圍:0~100。值越高,表示越有可能屬于該分類。 |
示例
請求示例
http(s)://[Endpoint]/green/image/scan
&<公共請求參數>
{
"scenes":["sface-1"],
"tasks":[
{
"url":"http://www.aliyundoc.com/2015/0826/2015082612403321.jpg",
"dataId":"e6b080a8-a91a-11e8-bac4-6c96cfde2af9",
"extras":{
"faceUrl":"http://www.aliyundoc.com/c/u/2013/0313/1363136852136.jpg"
}
}
]
}
返回示例
{
"code":200,
"msg":"OK",
"requestId":"9EEF894F-A933-4830-97B1-EC1A9630A9D6",
"data":[
{
"code":200,
"dataId":"e6b080a8-a91a-11e8-bac4-6c96cfde2af9",
"taskId":"img2hsbmQeA4CU7l78$s8q5mW-1pnn7Z",
"url":"http://www.aliyundoc.com/2015/0826/2015082612403321.jpg",
"extras":{
},
"msg":"OK",
"results":{
"label":"sface-1",
"rate":97,
"scene":"sface-1",
"suggestion":"review"
}
}
]
}