調用/green/image/asyncscan進行非同步檢測人臉比對 - Content Moderation

本文介紹了調用圖片非同步檢測介面（/green/image/asyncscan）進行人臉圖片1：1比對的方法。人臉比對協助您檢測兩張人臉照片的相似性。

（圖片非同步檢測）使用說明

業務介面：/green/image/asyncscan，表示圖片非同步檢測。

您可以調用該介面建立圖片非同步檢測任務。關於如何構造HTTP請求，請參見請求結構；您也可以直接選用已構造好的HTTP請求，更多資訊，請參見SDK概覽。

計費資訊：
該介面為收費介面。關於計費方式，請參見Alibaba Content Security Service產品定價。
說明
對於人臉比對功能，傳入兩張圖片進行一次比對進行一次計費，而不是兩次。
檢測逾時：
同步檢測允許的最長檢測時間是6秒，如果檢測在該時間限制內沒有完成，系統會強制返回逾時錯誤碼。如果您對即時性要求不高，可以選擇非同步檢測，其他情況下請選擇同步檢測，同步檢測介面的調用相對簡單些。對於同步檢測介面的調用，建議您將逾時時間設定為6秒。
返回結果：
非同步檢測任務不會即時返回檢測結果，您需要通過callback或者輪詢的方式擷取檢測結果。檢測結果最長保留一小時。
- callback擷取檢測結果：提交非同步檢測任務時，在請求參數中傳入callback參數，用來自動接收檢測結果，具體說明，請參見（非同步檢測）請求參數。
- 輪詢擷取檢測結果：提交非同步檢測任務時，無需傳入callback參數；提交非同步檢測任務後，調用結果查詢介面擷取檢測結果，具體說明，請參見（圖片非同步檢測結果查詢）使用說明。
圖片要求：
- 圖片連結支援以下協議：HTTP和HTTPS。
- 圖片支援以下格式：PNG、JPG、JPEG、BMP、GIF、WEBP。
- 圖片大小限制為20 MB以內（適用於同步和非同步呼叫）。
- 圖片下載時間限制為3秒內，如果下載時間超過3秒，返回下載逾時。
- 圖片像素建議不低於256*256（px），像素過低可能會影響識別效果。
- 圖片檢測介面的回應時間依賴圖片的下載時間。請保證被檢測圖片所在的儲存服務穩定可靠，建議您使用阿里雲OSS儲存或者CDN緩衝等。

QPS限制

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

（非同步檢測）請求參數

名稱	類型	是否必選	樣本值	描述
bizType	String	否	default	該欄位用於標識您的業務情境。您可以通過Alibaba Content Security Service控制台建立業務情境（具體操作，請參見自訂機審標準）。
scenes	StringArray	是	["sface-1"]	指定檢測情境，取值：sface-1，表示人臉比對。
callback	String	否	http://www.aliyundoc.com/xx.json	檢測結果回調通知您的URL，支援使用HTTP和HTTPS協議的地址。該欄位為空白時，您必須定時輪詢檢測結果。 callback介面必須支援POST方法、UTF-8編碼的傳輸資料，以及表單參數checksum和content。Alibaba Content Security Service按照以下規則和格式設定checksum和content，調用您的callback介面返回檢測結果。 checksum：字串格式，由`使用者uid + seed + content`拼成字串，通過SHA256演算法產生。使用者UID即阿里雲帳號ID，可以在阿里雲控制台查詢。為防篡改，您可以在擷取到推送結果時，按上述演算法產生字串，與checksum做一次校正。說明使用者UID必須是阿里雲帳號的UID，而不是RAM使用者的UID。 content：JSON字串格式，請自行解析反轉成JSON對象。關於content結果的樣本，請參見查詢檢測結果的返回樣本。說明您的服務端callback介面收到Alibaba Content Security Service推送的結果後，如果返回的HTTP狀態代碼為200，則表示接收成功，其他的HTTP狀態代碼均視為接收失敗。接收失敗時，Alibaba Content Security Service將最多重複推送16次檢測結果，直到接收成功。重複推送16次後仍未接收成功，則不再推送，建議您檢查callback介面的狀態。
seed	String	否	aabbcc123	隨機字串，該值用於回調通知請求中的簽名。由英文字母、數字、底線（_）組成，不超過64個字元。由您自訂，用於在接收到Alibaba Content Security Service的回調通知時校正請求由阿里雲Alibaba Content Security Service服務發起。說明當使用callback時，該欄位必須提供。
cryptType	String	否	SHA256	使用回調通知時（callback），設定對回調通知內容進行加密的演算法。Alibaba Content Security Service會將返回結果（由`使用者uid + seed + content`拼接的字串）按照您設定的密碼編譯演算法加密後，再發送到您的回調通知地址。取值： SHA256（預設）：使用SHA256密碼編譯演算法。 SM3：使用國密HMAC-SM3密碼編譯演算法，返回十六進位的字串，且字串由小寫字母和數字組成。例如，abc經國密SM3加密後返回66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0。
tasks	JSONArray	是		指定檢測對象，JSON數組中的每個元素是一個檢測任務結構體。最多支援100個元素，即每次提交100條內容進行檢測，支援100個元素的前提是需要將並發任務調整到100個以上。關於每個元素的具體結構描述，請參見task。

表 1. task
名稱	類型	是否必選	樣本值	描述
dataId	String	否	e6b080a8-a91a-11e8-bac4-6c96cfde2af9	檢測對象對應的資料ID。由大小寫英文字母、數字、底線（_）、短劃線（-）、英文句號（.）組成，不超過128個字元，可以用於唯一標識您的業務資料。
url	String	是	http://www.aliyundoc.com/2015/0826/2015082612403321.jpg	公網HTTP/HTTPS URL，且長度不超過2048個字元。說明傳入待比較圖片中的第一張圖片的URL。
extras	JSONObject	否	{"faceUrl":"http://www.aliyundoc.com/c/u/2013/0313/1363136852136.jpg"}	傳入待比較圖片中的第二張圖片。格式為`{"faceUrl":"http://xxx.jpg"}`。其中，`faceUrl`為第二張圖片的URL。

（非同步檢測）返回資料

名稱	類型	樣本值	描述
code	Integer	200	錯誤碼，和HTTP狀態代碼一致。更多資訊，請參見公用錯誤碼。
msg	String	OK	請求資訊的響應訊息。
dataId	String	e6b080a8-a91a-11e8-bac4-6c96cfde2af9	檢測對象對應的資料ID。說明如果在檢測請求參數中傳入了dataId，則此處返回對應的dataId。
taskId	String	fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695	檢測任務的ID。
url	String	http://www.aliyundoc.com/2015/0826/2015082612403321.jpg	公網HTTP/HTTPS URL，且長度不超過2048個字元。說明檢測對象的URL。對應請求中的URL，即第一張圖片的URL。

（非同步檢測）樣本

請求樣本

http(s)://[Endpoint]/green/image/asyncscan
&<公用請求參數>
{
    "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"
            },
            "time": 949640
        }
    ]
}

正常返回樣本

{
    "code": 200,
    "msg": "OK",
    "requestId": "95AD868A-F5D2-4AEA-96D4-E0273B8E074C",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "e6b080a8-a91a-11e8-bac4-6c96cfde2af9",
            "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
            "url": "http://www.aliyundoc.com/2015/0826/2015082612403321.jpg"
        }
    ]
}

（圖片非同步檢測結果查詢）使用說明

業務介面：/green/image/results，表示查詢圖片非同步檢測結果。

您可以調用該介面查詢圖片非同步檢測任務的結果。關於如何構造HTTP請求，請參見請求結構；您也可以直接選用已構造好的HTTP請求，更多資訊，請參見SDK概覽。

計費資訊：
該介面不計費。
查詢逾時：
建議您將查詢間隔設定為30秒（即在提交非同步檢測任務30秒後查詢結果），最長不能超出4個小時，否則結果將會丟失。

QPS限制

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

（結果查詢）請求參數

名稱	類型	是否必選	樣本值	描述
body	StringArray	是	["fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"]	要查詢的檢測任務的taskId列表。數組中的元素個數不超過100個。您在提交檢測任務後，可以從返回資料中擷取檢測任務的taskId。

（結果查詢）返回資料

名稱	類型	樣本值	描述
code	Integer	200	錯誤碼，和HTTP狀態代碼一致。更多資訊，請參見公用錯誤碼。
msg	String	OK	請求資訊的響應訊息。
dataId	String	e6b080a8-a91a-11e8-bac4-6c96cfde2af9	檢測對象對應的資料ID。說明如果在檢測請求參數中傳入了dataId，則此處返回對應的dataId。
taskId	String	img2hsbmQeA4CU7l78$s8q5mW-1pnn7Z	檢測任務的ID。
url	String	http://www.aliyundoc.com/2015/0826/2015082612403321.jpg	檢測對象的URL。
results	JSONArray		返回結果。調用成功時（code=200），返回結果中包含一個或多個元素。每個元素是個結構體，具體結構描述，請參見result。
extras	JSONObject	xxx	額外調用參數。說明該參數可能會被調整，目前請勿依賴該參數的傳回值。

表 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/results
&<公用請求參數>
[
    "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"
]

正常返回樣本

{
    "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.0,
                "scene": "sface-1",
                "suggestion": "review"
            }
        }
    ]
}