調用/green/image/scan進行人臉比對 - Content Moderation

本文提供了調用圖片同步檢測任務進行人臉1:1比對的具體介面和參數說明，旨在協助您編寫程式構建HTTP調用請求。

使用說明

業務介面：/green/image/scan

提交圖片同步檢測任務，進行人臉照片1:1比對，檢測兩張人臉照片的相似性。關於如何構造HTTP請求，請參見請求結構；您也可以直接選用已構造好的HTTP請求，更多資訊，請參見SDK概覽。

計費資訊：
該介面為收費介面。關於計費方式，請參見Alibaba Content Security Service產品定價。
說明
對於人臉比對功能，傳入兩張圖片進行一次比對進行一次計費（而不是兩次）。

檢測逾時：
同步檢測允許的最長檢測時間是6秒，如果檢測在該時間限制內沒有完成，系統會強制返回逾時錯誤碼。如果您對即時性要求不高，可以選擇非同步檢測；其它情況下，請選擇同步檢測，同步檢測介面的調用相對簡單些。對於同步檢測介面的調用，建議您將逾時時間設定為6秒。

圖片要求：
- 圖片連結支援以下協議：HTTP和HTTPS。
- 圖片支援以下格式：PNG、JPG、JPEG、BMP、GIF、WEBP。
- 圖片大小限制為20 MB以內（適用於同步和非同步呼叫）。
- 圖片下載時間限制為3秒內，如果下載時間超過3秒，返回下載逾時。
- 圖片像素建議不低於256*256（px），像素過低可能會影響識別效果。
- 圖片檢測介面的回應時間依賴圖片的下載時間。請保證被檢測圖片所在的儲存服務穩定可靠，建議您使用阿里雲OSS儲存或者CDN緩衝等。

QPS限制

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

請求參數

關於在請求中必須包含的公用請求參數，請參見公用參數。

請求body是一個JSON對象，欄位說明如下：

名稱	類型	是否必選	樣本值	描述
bizType	String	否	default	該欄位用於標識您的業務情境。您可以通過Alibaba Content Security Service控制台建立業務情境（具體操作，請參見自訂機審標準）。
scenes	StringArray	是	["sface-1"]	指定圖片檢測的應用情境，取值：sface-1。
tasks	JSONArray	是		指定檢測對象，JSON數組中的每個元素是一個檢測任務結構體。最多支援100個元素，即每次提交100條內容進行檢測，支援100個元素的前提是需要將並發任務調整到100個以上。關於每個元素的具體結構描述，請參見task。

表 1. task
名稱	類型	是否必選	樣本值	描述
dataId	String	否	e6b080a8-a91a-11e8-bac4-6c96cfde2af9	資料ID。需要保證在一次請求中所有的ID不重複。
url	String	是	http://www.aliyundoc.com/2015/0826/2015082612403321.jpg	公網HTTP/HTTPS URL，且長度不超過2048個字元。說明傳入待比較圖片中的第一張圖片的URL。
extras	Map	否	xxx	傳入待比較圖片中的第二張圖片。格式為`{"faceUrl":"http://xxx.jpg"}`。其中，`faceUrl`為第二張圖片的URL。

返回資料

返回結果說明，請參見返回結果。

返回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	公網HTTP/HTTPS URL，且長度不超過2048個字元。說明對應請求中的URL，即第一張圖片的URL。
extras	Map	xxx	額外調用參數。說明該參數可能會被調整，目前請勿依賴該參數的傳回值。
results	JSONArray	否	返回結果。調用成功時（code=200），返回結果中包含一個或多個元素。每個元素是個結構體，具體結構描述見result。

表 2. result
名稱	類型	樣本值	描述
scene	String	sface-1	風險情境，取值：sface-1。
label	String	sface-1	檢測結果的分類，取值： normal：第二張圖片與第一張圖片相似性低。 sface-1：第二張圖片與第一張圖片相似性高。
suggestion	String	review	建議使用者執行的操作，取值範圍： pass：圖片相似性低，無需進行其餘操作 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"
            }
        }
    ]
}