Face Recognition Operations - Find Similar From Large Face List

Service:

Azure AI Services

API Version:

v1.1-preview.1

給定查詢臉部的faceId，從大型臉部清單中搜尋類似外觀的臉部。 'largeFaceListId' 是由 Create 大型臉部列表所建立。
根據輸入，傳回的類似臉部清單包含faceId或依相似度排名的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	在「Create 大型臉部清單」中建立的現有使用者指定唯一候選大型臉部清單。 大型臉部清單包含一組保存的persistedFaceIds，且永遠不會過期。
maxNumOfCandidatesReturned		integer	傳回的最上層相似臉部數目。 有效範圍為 [1， 1000]。 預設值為 20。
mode		FindSimilarMatchMode	類似的臉部搜尋模式。 它可以是 'matchPerson' 或 'matchFace'。 默認值為 『matchPerson』。

回應

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

安全性

Ocp-Apim-Subscription-Key

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

Type: apiKey
In: header

AADToken

Azure Active Directory OAuth2 流程

Type: oauth2
Flow: accessCode
Authorization URL: https://api.example.com/oauth2/authorize
Token URL: https://api.example.com/oauth2/token

Scopes

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

範例

Find Similar from LargeFaceList

Sample Request

HTTP

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

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

Sample Response

Status code:

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 是由 「Detect」 所建立，且會在偵測呼叫之後 24 小時到期。
persistedFaceId	string	當 faceListId 或 largeFaceListId 找到時，候選臉部的 persistedFaceId。 臉部清單/大型臉部清單中的persistedFaceId會保存，且不會過期。