Face Recognition Operations - Find Similar From Large Face List

服務:

Azure AI Services

API 版本:

v1.2-preview.1

給定查詢臉部的faceId，從大型臉部清單搜尋類似外觀的臉部。 建立大型臉部清單會建立 『largeFaceListId』。
根據輸入，傳回的類似臉部清單包含faceIds或依相似度排名的persistedFaceId。

尋找類似的模式有兩種運作模式：「matchPerson」 和 「matchFace」。。 “matchPerson” 是預設模式，它會嘗試使用內部同一人員閾值來尋找同一個人的臉部。 尋找已知人員的其他相片很有用。 請注意，如果沒有臉部通過內部閾值，則會傳回空白清單。 “matchFace” 模式會忽略同一個人閾值，並傳回排名類似的臉部，即使相似度很低。 它可用於搜尋名人外觀的臉部等案例。

與查詢faceId相關聯的 'recognitionModel' 應該與目標大型臉部清單所使用的 'recognitionModel' 相同。

POST {endpoint}/face/{apiVersion}/findsimilars

URI 參數

名稱	位於	必要	類型	Description
apiVersion	path	True	string	API 版本
endpoint	path	True	string uri	支持的認知服務端點（通訊協定和主機名，例如：https://{resource-name}.cognitiveservices.azure.com）。

要求本文

名稱	必要	類型	Description
faceId	True	string	查詢臉部的faceId。 用戶必須先呼叫 「Detect」 才能取得有效的 faceId。 請注意，此 faceId 不會保存，且會在偵測呼叫之後 24 小時到期。
largeFaceListId	True	string	在「建立大型臉部清單」中建立的現有使用者指定唯一候選大型臉部清單。 大型臉部清單包含一組保存且永遠不會過期的persistedFaceId。
maxNumOfCandidatesReturned		integer	傳回的前相似臉部數目。 有效範圍為 [1， 1000]。 預設值為 20。
mode		FindSimilarMatchMode	類似的臉部搜尋模式。 它可以是 'matchPerson' 或 'matchFace'。 默認值為 『matchPerson』。

回應

名稱	類型	Description
200 OK	FindSimilarResult[]	如果輸入參數為faceId，或輸入參數為faceListId或 largeFaceListId，則成功的呼叫會傳回faceId中表示之最類似臉部的數位。
Other Status Codes	FaceErrorResponse	未預期的錯誤回應。 標題 x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

Azure AI 臉部訂用帳戶的秘密密鑰。

類型: apiKey
位於: header

AADToken

Azure Active Directory OAuth2 流程

類型: oauth2
Flow: accessCode
授權 URL: https://api.example.com/oauth2/authorize
權杖 URL: https://api.example.com/oauth2/token

範圍

名稱	Description
https://cognitiveservices.azure.com/.default

範例

Find Similar from LargeFaceList

範例要求

HTTP

POST {endpoint}/face/v1.2-preview.1/findsimilars

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

範例回覆

狀態碼:

200

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

定義

名稱	Description
FaceError	error 物件。 如需臉部服務所傳回錯誤碼和訊息的完整詳細數據，請參閱下列連結：https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含錯誤詳細數據的回應。
FindSimilarResult	尋找類似臉部作業的回應本文。

FaceError

error 物件。 如需臉部服務所傳回錯誤碼和訊息的完整詳細數據，請參閱下列連結：https://aka.ms/face-error-codes-and-messages。

名稱	類型	Description
code	string	其中一組伺服器定義的錯誤碼。
message	string	錯誤的人類可讀取表示法。

FaceErrorResponse

包含錯誤詳細數據的回應。

名稱	類型	Description
error	FaceError	error 物件。

FindSimilarResult

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

名稱	類型	Description
confidence	number	候選專案的信心值。 信賴度越高，越相似。 範圍介於 [0,1]。
faceId	string	faceIds 找到時，候選臉部的faceId。 faceId 是由 「偵測」所建立，且會在偵測呼叫之後 24 小時到期。
persistedFaceId	string	當 faceListId 或 largeFaceListId 找到時，候選臉部的 persistedFaceId。 臉部清單/大型臉部清單中的persistedFaceId會保存，且不會過期。