Face - Find Similar

參考

Service:: Cognitive Services - Face

API Version:: 1.0

根據查詢臉部的 faceId，從 faceId 陣列、臉部清單或大型臉部清單搜尋長相相似的人臉。 faceId 陣列包含 Face - Detect With Url 或 Face - Detect With Stream 所建立的臉部，這會在建立後由 faceIdTimeToLive 指定的時間到期。 “ faceListId” 是由 FaceList 所建立 - 建立包含不會過期的 persistedFaceIds。而「 largeFaceListId」是由 LargeFaceList - 建立包含不會過期的 persistedFaceIds。根據輸入，傳回的類似臉部清單包含faceId或依相似性排名的persistedFaceIds。
尋找類似的有兩種運作模式：「matchPerson」和「matchFace」。。 “matchPerson” 是預設模式，它會嘗試使用內部相同人員閾值來尋找相同人員的人臉。尋找已知人員的其他相片很有用。請注意，如果沒有臉部通過內部閾值，則會傳回空的清單。 “matchFace” 模式會忽略相同人員閾值，並傳回排名類似的臉部，即使相似度很低也一樣。它可用於搜尋名人外觀臉部等案例。
與查詢臉部 faceId 相關聯的 'recognitionModel' 應該與目標 faceId 陣列、臉部清單或大型臉部清單所使用的 'recognitionModel' 相同。

POST {Endpoint}/face/v1.0/findsimilars

URI 參數

名稱	位於	必要	類型	Description
Endpoint	path	True	string	支援的認知服務端點 (通訊協定和主機名，例如： https://westus.api.cognitive.microsoft.com) 。

要求標頭

名稱	必要	類型	Description
Ocp-Apim-Subscription-Key	True	string

要求本文

名稱	必要	類型	Description
faceId	True	string	查詢臉部的FaceId。用戶必須呼叫 Face - 先偵測以取得有效的 faceId。請注意，此 faceId 不會保存，而且會在偵測呼叫之後由 faceIdTimeToLive 指定的時間到期
faceIds		string[]	候選faceIds的陣列。所有物件都是由Face - Detect所建立，而faceIds會在偵測呼叫之後由faceIdTimeToLive指定的時間到期。 faceId 的數目限制為1000。參數 faceListId、largeFaceListId 和 faceId 不應該同時提供。
faceListId		string	在臉部清單中建立的現有使用者指定唯一候選臉部清單 - 建立臉部清單。臉部清單包含一組保存的 PersistedFaceIds，這些標識碼會保存且永遠不會過期。參數 faceListId、largeFaceListId 和 faceId 不應該同時提供。
largeFaceListId		string	在 LargeFaceList - Create 中建立的現有使用者指定唯一候選大型臉部清單。大型臉部清單包含一組保存且永遠不會過期的persistedFaceId。參數 faceListId、largeFaceListId 和 faceId 不應該同時提供。
maxNumOfCandidatesReturned		integer	傳回的最上層相似臉部數目。有效範圍為 [1， 1000]。
mode		FindSimilarMatchMode	類似的臉部搜尋模式。它可以是「matchPerson」或「matchFace」。

回應

名稱	類型	Description
200 OK	SimilarFace[]	如果輸入參數是faceId，則成功呼叫會傳回faceId中所表示最類似臉部的陣列，如果輸入參數是faceListId，則傳回persistedFaceId。
Other Status Codes	APIError	錯誤回應。

安全性

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

範例

Find similar results example

Sample Request

HTTP

POST {Endpoint}/face/v1.0/findsimilars


{
  "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
  "largeFaceListId": "sample_list",
  "maxNumOfCandidatesReturned": 1,
  "mode": "matchPerson"
}

Sample Response

Status code:: 200

[
  {
    "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9",
    "confidence": 0.82
  }
]

定義

名稱	Description
APIError	API 傳回的錯誤資訊
Error	錯誤本文。
FindSimilarMatchMode	類似的臉部搜尋模式。它可以是「matchPerson」或「matchFace」。
FindSimilarRequest	尋找類似作業的要求本文。
SimilarFace	尋找類似臉部作業的回應本文。

APIError

API 傳回的錯誤資訊

名稱	類型	Description
error	Error	錯誤本文。

Error

錯誤本文。

名稱	類型	Description
code	string
message	string

FindSimilarMatchMode

類似的臉部搜尋模式。它可以是「matchPerson」或「matchFace」。

名稱	類型	Description
matchFace	string
matchPerson	string

FindSimilarRequest

尋找類似作業的要求本文。

名稱	類型	預設值	Description
faceId	string		查詢臉部的FaceId。用戶必須呼叫 Face - 先偵測以取得有效的 faceId。請注意，此 faceId 不會保存，而且會在偵測呼叫之後由 faceIdTimeToLive 指定的時間到期
faceIds	string[]		候選faceIds的陣列。所有物件都是由Face - Detect所建立，而faceIds會在偵測呼叫之後由faceIdTimeToLive指定的時間到期。 faceId 的數目限制為1000。參數 faceListId、largeFaceListId 和 faceId 不應該同時提供。
faceListId	string		在臉部清單中建立的現有使用者指定唯一候選臉部清單 - 建立臉部清單。臉部清單包含一組保存的 PersistedFaceIds，這些標識碼會保存且永遠不會過期。參數 faceListId、largeFaceListId 和 faceId 不應該同時提供。
largeFaceListId	string		在 LargeFaceList - Create 中建立的現有使用者指定唯一候選大型臉部清單。大型臉部清單包含一組保存且永遠不會過期的persistedFaceId。參數 faceListId、largeFaceListId 和 faceId 不應該同時提供。
maxNumOfCandidatesReturned	integer	20	傳回的最上層相似臉部數目。有效範圍為 [1， 1000]。
mode	FindSimilarMatchMode	matchPerson	類似的臉部搜尋模式。它可以是「matchPerson」或「matchFace」。

SimilarFace

尋找類似臉部作業的回應本文。

名稱	類型	Description
confidence	number	候選臉部的相似度信賴度。信賴度越高，比較類似。介於 [0,1] 之間的範圍。
faceId	string	由faceIds尋找時，候選臉部的FaceId。 faceId 是由 Face - Detect 建立，且會在偵測呼叫之後由 faceIdTimeToLive 指定的時間到期
persistedFaceId	string	由 faceListId 尋找時，候選臉部的 PersistedFaceId。臉部清單中的persistedFaceId會保存且不會過期。如下列回應所示