Face Recognition Operations - Find Similar From Large Face List

서비스:

Azure AI Services

API 버전:

v1.2-preview.1

큰 얼굴 목록에서 비슷한 얼굴을 검색하는 쿼리 얼굴의 faceId가 지정됩니다. 'largeFaceListId'는 큰 얼굴 목록 만들기를 통해 만들어집니다.
입력에 따라 반환된 유사한 얼굴 목록에는 유사성에 따라 순위가 지정된 faceId 또는 persistedFaceId가 포함됩니다.

유사 항목 찾기에는 "matchPerson" 및 "matchFace"라는 두 가지 작업 모드가 있습니다. "matchPerson"은 내부 동일한 사람 임계값을 사용하여 가능한 한 동일한 사람의 얼굴을 찾으려고 시도하는 기본 모드입니다. 알려진 사람의 다른 사진을 찾는 것이 유용합니다. 내부 임계값을 통과하는 얼굴이 없으면 빈 목록이 반환됩니다. "matchFace" 모드는 동일한 사람 임계값을 무시하고 유사성이 낮더라도 순위가 지정된 유사한 얼굴을 반환합니다. 그것은 유명 인사 찾고 얼굴을 검색 같은 경우에 사용할 수 있습니다.

쿼리 faceId와 연결된 'recognitionModel'은 대상 큰 얼굴 목록에서 사용하는 'recognitionModel'과 동일해야 합니다.

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

URI 매개 변수

Name	In(다음 안에)	필수	형식	Description
apiVersion	path	True	string	API 버전
endpoint	path	True	string uri	지원되는 Cognitive Services 엔드포인트(프로토콜 및 호스트 이름, 예: https://{resource-name}.cognitiveservices.azure.com).

요청 본문

Name	필수	형식	Description
faceId	True	string	쿼리 얼굴의 faceId입니다. 사용자는 유효한 faceId를 얻으려면 먼저 "Detect"를 호출해야 합니다. 이 faceId는 유지되지 않으며 검색 호출 후 24시간 후에 만료됩니다.
largeFaceListId	True	string	"큰 얼굴 목록 만들기"에서 만든 기존 사용자 지정 고유 후보 큰 얼굴 목록입니다. 큰 얼굴 목록에는 지속형FaceId 집합이 포함되어 있으며 지속되며 만료되지 않습니다.
maxNumOfCandidatesReturned		integer	반환된 상위 유사한 얼굴의 수입니다. 유효한 범위는 [1, 1000]입니다. 기본값은 20입니다.
mode		FindSimilarMatchMode	비슷한 얼굴 검색 모드입니다. 'matchPerson' 또는 'matchFace'일 수 있습니다. 기본값은 'matchPerson'입니다.

응답

Name	형식	Description
200 OK	FindSimilarResult[]	입력 매개 변수가 faceIds이거나 입력 매개 변수가 faceListId 또는 largeFaceListId인 경우 persistedFaceId인 경우 성공적인 호출은 faceId에 표시되는 가장 유사한 얼굴의 배열을 반환합니다.
Other Status Codes	FaceErrorResponse	예기치 않은 오류 응답입니다. 헤더 x-ms-error-code: string

보안

Ocp-Apim-Subscription-Key

Azure AI Face 구독의 비밀 키입니다.

형식: apiKey
In(다음 안에): header

AADToken

Azure Active Directory OAuth2 흐름

형식: oauth2
Flow: accessCode
권한 부여 URL: https://api.example.com/oauth2/authorize
토큰 URL: https://api.example.com/oauth2/token

범위

Name	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"
  }
]

정의

Name	Description
FaceError	오류 개체입니다. Face Service에서 반환된 오류 코드 및 메시지에 대한 포괄적인 세부 정보는 다음 링크를 참조하세요. https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	오류 세부 정보가 포함된 응답입니다.
FindSimilarResult	유사한 얼굴 작업을 찾기 위한 응답 본문입니다.

FaceError

오류 개체입니다. Face Service에서 반환된 오류 코드 및 메시지에 대한 포괄적인 세부 정보는 다음 링크를 참조하세요. https://aka.ms/face-error-codes-and-messages.

Name	형식	Description
code	string	서버에서 정의한 오류 코드 집합 중 하나입니다.
message	string	사람이 읽을 수 있는 오류 표현입니다.

FaceErrorResponse

오류 세부 정보가 포함된 응답입니다.

Name	형식	Description
error	FaceError	오류 개체입니다.

FindSimilarResult

유사한 얼굴 작업을 찾기 위한 응답 본문입니다.

Name	형식	Description
confidence	number	후보자의 신뢰도 값입니다. 신뢰도가 높을수록 더 비슷합니다. [0,1] 사이의 범위입니다.
faceId	string	faceIds로 찾을 때 후보 얼굴의 faceId입니다. faceId는 "Detect"에 의해 생성되며 검색 호출 후 24시간 후에 만료됩니다.
persistedFaceId	string	faceListId 또는 largeFaceListId에서 찾을 때 후보 얼굴의 persistedFaceId입니다. 얼굴 목록/큰 얼굴 목록의 persistedFaceId가 유지되며 만료되지 않습니다.