Face Recognition Operations - Find Similar From Large Face List

サービス:

Azure AI Services

API バージョン:

v1.2-preview.1

クエリ顔の faceId を指定して、大きな顔リストから類似した顔を検索します。 "largeFaceListId" は、大きな顔リストを作成することによって作成されます。
入力に応じて、返される類似した顔の一覧には、類似度でランク付けされた faceIds または persistedFaceIds が含まれます。

類似検索には、"matchPerson" と "matchFace" の 2 つの動作モードがあります。 "matchPerson" は、内部の同じ人物のしきい値を使用して、同じ人物の顔を見つけようとする既定のモードです。 これは、既知の人の他の写真を見つけるのに役立ちます。 内部しきい値を超える顔がない場合は、空のリストが返されることに注意してください。 "matchFace" モードでは、同じ人物のしきい値が無視され、ランク付けされた類似した顔が返されます。類似性が低い場合でも同様です。 有名人のような顔を検索する場合に使用できます。

クエリ faceId に関連付けられている 'recognitionModel' は、ターゲットの Large Face List で使用される 'recognitionModel' と同じである必要があります。

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

URI パラメーター

名前	/	必須	型	説明
apiVersion	path	True	string	API バージョン
endpoint	path	True	string uri	サポートされている Cognitive Services エンドポイント (プロトコルとホスト名。例: https://{resource-name}.cognitiveservices.azure.com)。

要求本文

名前	必須	型	説明
faceId	True	string	クエリ顔の faceId。 有効な faceId を取得するには、まず "Detect" を呼び出す必要があります。 この faceId は永続化されず、検出呼び出しの 24 時間後に期限切れになります。
largeFaceListId	True	string	既存のユーザー指定の一意の候補 Large Face List。「大きな顔リストの作成」で作成されます。 Large Face List には、永続化され、期限切れになることのない一連の永続化されたFaceId が含まれています。
maxNumOfCandidatesReturned		integer	返された上位の類似した顔の数。 有効な範囲は [1, 1000] です。 既定値は 20 です。
mode		FindSimilarMatchMode	同様の顔検索モード。 'matchPerson' または 'matchFace' を指定できます。 既定値は 'matchPerson' です。

応答

名前	型	説明
200 OK	FindSimilarResult[]	入力パラメーターが faceListId または largeFaceListId の場合、入力パラメーターが faceIds または persistedFaceId の場合、正常に呼び出されると、faceId で表される最も類似した顔の配列が返されます。
Other Status Codes	FaceErrorResponse	予期しないエラー応答。 ヘッダー x-ms-error-code: string

セキュリティ

Ocp-Apim-Subscription-Key

Azure AI Face サブスクリプションの秘密鍵。

型: apiKey
/: header

AADToken

Azure Active Directory OAuth2 フロー

型: oauth2
フロー: accessCode
Authorization URL (承認 URL): https://api.example.com/oauth2/authorize
Token URL (トークン URL): https://api.example.com/oauth2/token

スコープ

名前	説明
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"
  }
]

定義

名前	説明
FaceError	エラー オブジェクト。 Face サービスによって返されるエラー コードとメッセージの詳細については、次のリンクを参照してください: https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	エラーの詳細を含む応答。
FindSimilarResult	類似した顔の検索操作の応答本文。

FaceError

エラー オブジェクト。 Face サービスによって返されるエラー コードとメッセージの詳細については、次のリンクを参照してください: https://aka.ms/face-error-codes-and-messages。

名前	型	説明
code	string	サーバー定義の一連のエラー コードの 1 つ。
message	string	エラーの人間が判読できる表現。

FaceErrorResponse

エラーの詳細を含む応答。

名前	型	説明
error	FaceError	エラー オブジェクト。

FindSimilarResult

類似した顔の検索操作の応答本文。

名前	型	説明
confidence	number	候補の信頼度値。 信頼度が高いほど、類似しています。 [0,1] の範囲。
faceId	string	faceIds で検索する場合の候補顔の faceId。 faceId は "Detect" によって作成され、検出呼び出しの 24 時間後に有効期限が切れます。
persistedFaceId	string	faceListId または largeFaceListId で検索した場合の候補の顔の persistedFaceId。 顔リスト/大きな顔リストの persistedFaceId は永続化され、有効期限は切れなくなります。