本文介紹了調用圖片同步檢測（imageScan）介面進行自訂人臉檢索的方法。自訂人臉檢索能夠從指定的個體庫中檢索特定的人臉圖片，並返回與目標最相似的5個個體。
情境說明
自訂人臉檢索根據您傳入的待識別人臉圖片（face），在個體組（group）中尋找並返回Top 5最相似的個體（person），返回的Top 5個體按照相似性從大到小排序。
參數 | 說明 | 相關介面 |
person | 個體，表示一個自然人。 | |
face | 人臉，表示個體關聯的人臉圖片。 一個個體可以關聯多個人臉圖片。 | |
group | 個體組，表示個體的集合。 一個個體可以屬於多個組，一個組也可以包含多個個體。 |
使用說明
您可以調用imageScan介面建立圖片同步檢測任務。關於如何構造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調用會被限流，這可能會影響您的業務，請合理調用。
請求文法
POST /green/image/scan HTTPS|HTTP要求標頭
該介面使用公用要求標頭，無特殊要求標頭。請參見公用要求標頭。
請求參數
名稱 | 類型 | 是否必選 | 樣本值 | 描述 |
clientInfo | JSONObject | 否 | {"userId":"120234234","userNick":"Mike","userType":"others"} | 用戶端資訊，由ClientInfo結構體通過JSON序列化獲得，包含umid、imei等資訊，具體結構描述，請參見ClientInfo。 |
RequestBody
RequestBody中還需要填入以下參數，用來指定檢測情境和任務資訊。
名稱 | 類型 | 是否必選 | 樣本值 | 描述 |
bizType | String | 否 | edu | 業務情境類型。自訂人臉檢索情境下無需傳入該參數。 |
scenes | StringArray | 是 | ["sface-n"] | 檢測情境，取值：sface-n，表示自訂人臉檢索。 |
tasks | JSONArray | 是 | 待檢測人臉圖片的資訊。具體結構描述，請參見task。 |
表 1. task
名稱 | 類型 | 是否必選 | 樣本值 | 描述 |
dataId | String | 否 | test2NInmOtAON6qYUrtCRgLo-1mwxdi | 檢測對象對應的資料ID。 由大小寫英文字母、數字、底線（_）、短劃線（-）、英文句號（.）組成，不超過128個字元，可以用於唯一標識您的業務資料。 |
url | String | 是 | https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png | 待檢測人臉圖片的URL。 |
extras | JSONObject | 是 | {"groupId":"group"} | 額外請求參數，傳入與待檢測圖片進行比對的個體組ID（groupId）。 您可以調用/green/sface/groups查詢所有的個體組ID。 |
返回資料
所有請求均返回JSON格式的資料。關於返回資料中的公用欄位，請參見公用返回參數。返回資料中的data欄位表示與業務相關的資料，一般是一個JSON結構體或數組。
響應出錯的情況下，data欄位可能為空白。
該介面返回的data欄位包含以下參數。
名稱 | 類型 | 樣本值 | 描述 |
code | Integer | 200 | 錯誤碼，和HTTP狀態代碼一致。 更多資訊，請參見公用錯誤碼。 |
results | JSONArray | 返回結果。調用成功時（code=200），返回結果中包含一個或多個result元素。每個result元素是個結構體，具體結構描述，請參見result。 |
表 2. result
名稱 | 類型 | 樣本值 | 描述 |
scene | String | sface-n | 檢測情境，取值：sface-n，表示自訂人臉檢索。 |
label | String | sface-n | 檢測結果的分類，取值：
|
suggestion | String | review | 建議您執行的操作，取值：
|
rate | Float | 0.999 | 結果屬於當前分類的機率，取值範圍：0.00~1.00。值越高，表示越有可能屬於當前分類。 |
topPersonData | JSONArray | 與目標人臉圖片最相似的5個個體資訊。具體結構描述，請參見topPersonData。 說明 如果未檢索到相似個體，則返回空值。 |
表 3. topPersonData
名稱 | 類型 | 樣本值 | 描述 |
persons | JSONArray | Top 5匹配個體的資訊。具體結構描述，請參見person。 | |
faceItem | JSONObject | 檢測映像中的人臉屬性。具體結構描述，請參見faceItem。 |
表 4. person
名稱 | 類型 | 樣本值 | 描述 |
personId | String | person1 | 匹配個體的ID。 |
faceId | String | 14736649593638 | 匹配個體的人臉圖片ID。 |
rate | Float | 0.999 | 個體的匹配機率。匹配機率越高，對應的誤識率越低，具體如下：
推薦您使用匹配機率取值在0.9以上的結果。 |
表 5. faceItem
名稱 | 類型 | 樣本值 | 描述 |
x | Float | 467 | 人臉在x軸的座標，單位：像素。 |
y | Float | 199 | 人臉在y軸的座標，單位：像素。 |
width | Float | 422 | 人臉寬度，單位：像素。 |
height | Float | 422 | 人臉高度，單位：像素。 |
樣本
請求樣本
POST /green/image/scan HTTP/1.1
公用要求標頭
{
"scenes": [
"sface-n"
],
"tasks": [
{
"dataId": "test2NInmOtAON6qYUrtCRgLo-1mwxdi",
"url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png",
"extras": {
"groupId": "group"
}
}
]
}正常返回樣本
{
"code": 200,
"data": [
{
"code": 200,
"dataId": "test2NInmOtAON6qYUrtCRgLo-1mwxdi",
"msg": "調用成功。",
"results": [
{
"topPersonData": [
{
"faceItem": {
"height": 422,
"width": 422,
"x": 467,
"y": 199
},
"persons": [
{
"faceId": "14736649593638",
"personId": "person1",
"rate": "0.999"
},
{
"faceId": "14736649593637",
"personId": "person2",
"rate": "0.998"
}
]
}
],
"label": "sface-n",
"rate": 0.999,
"scene": "sface-n",
"suggestion": "review"
}
],
"taskId": "img2MVcKPU1QGD64LoAb4cK6w-1mwxdi",
"url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
}
],
"msg": "OK",
"requestId": "36D384DA-8023-4E84-BCFD-0C5581352C16"
}