Face Recognition Operations - Find Similar From Face List

サービス:

Azure AI Services

API バージョン:

v1.1-preview.1

クエリ顔の faceId を指定して、顔リストから類似した顔を検索します。 'faceListId' は、Face List によって作成Create。
返される類似顔リストには、入力に応じて、類似度でランク付けされた faceIds または persistedFaceIds が含まれます。

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

クエリ faceId に関連付けられている 'recognitionModel' は、ターゲット 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 時間後に期限切れになることに注意してください。
faceListId	True	string	"Create Face List" で作成された既存のユーザー指定の一意の候補 Face List。 Face List には、永続化され、期限切れになることのない一連の persistedFaceId が含まれています。
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 FaceList

要求のサンプル

HTTP

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

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

応答のサンプル

状態コード:

200

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

定義

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

FaceError

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

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

FaceErrorResponse

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

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

FindSimilarResult

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

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