Liveness Session Operations - Create Liveness With Verify Session

참조

서비스:: Azure AI Services

API 버전:: v1.2

확인을 사용하여 새 활동성 세션을 만듭니다. 세션을 만드는 동안 확인 이미지를 제공합니다.
세션은 개발자가 리소스에 대한 모든 액세스 권한을 부여하지 않고 활동성 검색만 수행하도록 클라이언트 디바이스에 권한을 부여하려는 클라이언트 디바이스 시나리오에 가장 적합합니다. 만든 세션은 수명이 제한되어 있으며 액세스가 만료되기 전에 클라이언트가 원하는 작업을 수행할 수 있는 권한만 부여합니다.

사용 권한에는 다음이 포함됩니다.

- 최대 3번의 재시도에 대해 /detectLivenessWithVerify/singleModal을 호출하는 기능입니다.
- 토큰 수명(10분)입니다.

메모

- 클라이언트 액세스는 활성도 삭제 및 세션 확인 작업을 사용하여 세션을 삭제하여 취소할 수 있습니다.
- 결과를 검색하려면 Get Liveness With Verify 세션을 사용합니다.
- 클라이언트가 리소스에 대해 수행한 개별 요청을 감사하려면 세션 감사 항목 확인을 사용하여 활동성 목록을 사용합니다.

POST {endpoint}/face/{apiVersion}/detectLivenessWithVerify-sessions

URI 매개 변수

Name	In(다음 안에)	필수	형식	Description
livenessOperationMode	formData	True	LivenessOperationMode	클라이언트가 따라야 하는 활동 모드의 유형입니다.
verifyImage	formData	True	file	확인할 이미지 스트림입니다. 이 파트의 콘텐츠 처리 헤더 필드에는 파일 이름이 있어야 합니다.
authTokenTimeToLiveInSeconds	formData		integer int32	세션이 지속되어야 하는 시간(초)입니다. 범위는 60~86400초입니다. 기본값은 600입니다.
deviceCorrelationId	formData		string	각 최종 사용자 디바이스당 고유 Guid입니다. 이는 속도 제한 및 망치 방지를 제공하기 위한 것입니다. 이 요청에서 'deviceCorrelationIdSetInClient'가 true이면 이 'deviceCorrelationId'는 null이어야 합니다.
deviceCorrelationIdSetInClient	formData		boolean	클라이언트가 Vision SDK를 통해 자체 'deviceCorrelationId'를 설정할 수 있도록 허용할지 여부입니다. 기본값은 false이며 이 요청 본문에서 'deviceCorrelationId'를 설정해야 합니다.
enableSessionImage	formData		boolean	세션 이미지를 저장할지 여부입니다.
livenessModelVersion	formData		LivenessModel	활동성 분류에 사용되는 모델 버전입니다. 이는 선택적 매개 변수이며, 이 매개 변수를 지정하지 않으면 지원되는 최신 모델 버전이 선택됩니다.
returnVerifyImageHash	formData		boolean	확인 이미지 해시를 반환할지 여부입니다.
verifyConfidenceThreshold	formData		number float	얼굴 확인의 신뢰도 임계값입니다. 자세한 내용은 설명서를 참조하세요. https://learn.microsoft.com/legal/cognitive-services/face/characteristics-and-limitations?context=%2Fazure%2Fai-services%2Fcomputer-vision%2Fcontext%2Fcontext#recognition-confidence-score
apiVersion	path	True	string	API 버전
endpoint	path	True	string uri	지원되는 Cognitive Services 엔드포인트(프로토콜 및 호스트 이름, 예: https://{resource-name}.cognitiveservices.azure.com).

응답

Name	형식	Description
200 OK	LivenessWithVerifySession	성공적인 호출은 클라이언트 디바이스에 대한 세션을 만들고 제한된 목적과 시간 동안 클라이언트 애플리케이션에서 사용할 권한 부여 토큰을 제공합니다.
Other Status Codes	FaceErrorResponse	예기치 않은 오류 응답입니다. 헤더 x-ms-error-code: string

Name

형식

Description

200 OK

LivenessWithVerifySession

성공적인 호출은 클라이언트 디바이스에 대한 세션을 만들고 제한된 목적과 시간 동안 클라이언트 애플리케이션에서 사용할 권한 부여 토큰을 제공합니다.

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

예제

Create LivenessWithVerify Session

샘플 요청

HTTP

POST {endpoint}/face/v1.2/detectLivenessWithVerify-sessions

샘플 응답

상태 코드:: 200

{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm",
  "status": "NotStarted",
  "modelVersion": "2024-11-15",
  "results": {
    "attempts": [],
    "verifyReferences": [
      {
        "referenceType": "image",
        "faceRectangle": {
          "top": 316,
          "left": 131,
          "width": 498,
          "height": 677
        },
        "qualityForRecognition": "high"
      }
    ]
  }
}

정의

Name	Description
FaceError	오류 개체입니다. Face Service에서 반환된 오류 코드 및 메시지에 대한 포괄적인 세부 정보는 다음 링크를 참조하세요. https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	오류 세부 정보가 포함된 응답입니다.
FaceRectangle	얼굴을 찾을 수 있는 사각형입니다.
ImageType	이미지의 형식입니다.
LivenessColorDecisionTarget	활동성 분류에 사용되는 색 이미지의 대상입니다.
LivenessDecision	활동성 분류의 결과입니다.
LivenessDecisionTargets	활동성 분류에 사용되는 대상입니다.
LivenessError	활동성 분류의 오류입니다.
LivenessModel	활동성 분류에 사용되는 모델 버전입니다.
LivenessOperationMode	클라이언트의 최종 사용자 환경을 구동하는 활동성 작업 모드입니다.
LivenessWithVerifyOutputs	얼굴 확인 출력입니다.
LivenessWithVerifyReference	확인을 위한 얼굴의 세부 정보입니다.
LivenessWithVerifyResult	확인 호출을 사용한 활동성 결과입니다.
LivenessWithVerifySession	확인을 사용하여 활동성을 감지한 세션 결과입니다.
LivenessWithVerifySessionAttempt	세션 확인 시도가 있는 활동성입니다.
LivenessWithVerifySessionResults	확인 세션을 사용한 활동성 결과입니다.
OperationState	세션의 현재 상태입니다.
QualityForRecognition	인식에 대한 이미지 품질을 나타냅니다.

FaceError

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

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

FaceErrorResponse

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

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

FaceRectangle

얼굴을 찾을 수 있는 사각형입니다.

Name	형식	Description
height	integer	사각형의 높이(픽셀)입니다.
left	integer	이미지가 사각형의 왼쪽 가장자리까지인 경우 왼쪽 가장자리로부터의 거리(픽셀)입니다.
top	integer	이미지가 사각형의 위쪽 가장자리까지의 경우 위쪽 가장자리와의 거리(픽셀)입니다.
width	integer	사각형의 너비(픽셀)입니다.

ImageType

이미지의 형식입니다.

Name	형식	Description
Color	string	색 이미지입니다.
Depth	string	깊이 이미지입니다.
Infrared	string	적외선 이미지입니다.

LivenessColorDecisionTarget

활동성 분류에 사용되는 색 이미지의 대상입니다.

Name	형식	Description
faceRectangle	FaceRectangle	활동성 분류가 이루어진 얼굴 영역입니다.

LivenessDecision

활동성 분류의 결과입니다.

Name	형식	Description
realface	string	알고리즘은 대상 얼굴을 실제 얼굴로 분류했습니다.
spoofface	string	알고리즘은 대상 얼굴을 스푸핑으로 분류했습니다.
uncertain	string	알고리즘은 대상 얼굴을 실제 또는 스푸핑으로 분류할 수 없습니다.

LivenessDecisionTargets

활동성 분류에 사용되는 대상입니다.

Name	형식	Description
color	LivenessColorDecisionTarget	활동성 분류에 사용되는 색 이미지의 대상입니다.

LivenessError

활동성 분류의 오류입니다.

Name	형식	Description
code	string	오류 코드입니다.
message	string	오류 메시지입니다.
targets	LivenessDecisionTargets	활동성 분류에 사용되는 대상입니다.

LivenessModel

활동성 분류에 사용되는 모델 버전입니다.

Name	형식	Description
2024-11-15	string

LivenessOperationMode

클라이언트의 최종 사용자 환경을 구동하는 활동성 작업 모드입니다.

Name	형식	Description
Passive	string	사용자의 추가 작업이 필요하지 않은 수동 활동 기술을 활용합니다. 최적의 성능을 위해서는 정상적인 실내 조명과 높은 화면 밝기가 필요합니다. 따라서 이 모드는 작동 범위가 좁으며 최종 사용자가 밝은 조명 조건에 있어야 하는 시나리오에는 적합하지 않습니다. 참고: 모바일(iOS 및 Android) 솔루션에서 유일하게 지원되는 모드입니다.
PassiveActive	string	이 모드는 사용자 협력이 필요한 하이브리드 수동 또는 활성 활동 기술을 활용합니다. 최적화되지 않은 조명 조건에서만 활성 동작이 필요하도록 최적화되었습니다. 수동 모드와 달리 이 모드에는 조명 제한이 없으므로 더 광범위한 작동 봉투를 제공합니다. 이 모드는 웹 기반 솔루션에서 수동 모드의 작동 봉투를 방해하는 브라우저에서 사용할 수 있는 자동 화면 밝기 컨트롤이 없기 때문에 웹 기반 솔루션에서 선호됩니다.

LivenessWithVerifyOutputs

얼굴 확인 출력입니다.

Name	형식	Description
isIdentical	boolean	대상 활동성 얼굴 및 비교 이미지 얼굴 일치 여부입니다.
matchConfidence	number	대상 얼굴 활동성 얼굴 및 비교 이미지 얼굴 확인 신뢰도입니다.

LivenessWithVerifyReference

확인을 위한 얼굴의 세부 정보입니다.

Name	형식	Description
faceRectangle	FaceRectangle	비교 이미지의 분류가 만들어진 얼굴 영역입니다.
qualityForRecognition	QualityForRecognition	인식을 위한 얼굴 이미지의 품질입니다.
referenceType	ImageType	활동성 분류가 이루어진 얼굴 사각형을 포함하는 이미지 유형입니다.

LivenessWithVerifyResult

확인 호출을 사용한 활동성 결과입니다.

Name	형식	Description
digest	string	이 요청에 대한 서버 계산 다이제스트입니다. 보고된 클라이언트 다이제스트가 서버 계산 다이제스트와 다른 경우 클라이언트와 서비스 간의 메시지 무결성이 손상되어 결과를 신뢰할 수 없습니다. 자세한 내용은 이 값을 활용하여 엔드 투 엔드 솔루션을 보호하는 방법에 대한 가이드를 참조하세요.
livenessDecision	LivenessDecision	대상 얼굴의 활동성 분류입니다.
sessionImageId	string	세션 요청의 이미지 ID입니다.
targets	LivenessDecisionTargets	활동성 분류에 사용되는 대상입니다.
verifyImageHash	string	요청에서 verify-image의 sha256 해시입니다.
verifyResult	LivenessWithVerifyOutputs	얼굴 확인 출력입니다. 요청이 확인이 있는 활동성인 경우에만 사용할 수 있습니다.

LivenessWithVerifySession

확인을 사용하여 활동성을 감지한 세션 결과입니다.

Name	형식	Description
authToken	string	클라이언트 애플리케이션에서 실행되는 Vision SDK에 대한 인증을 제공하는 전달자 토큰입니다. 이 전달자 토큰에는 필요한 작업만 수행할 수 있는 권한이 제한되어 있으며 TTL 시간 후에 만료됩니다. 또한 감사할 수 있습니다.
modelVersion	LivenessModel	활동성 분류에 사용되는 모델 버전입니다. 이는 선택적 매개 변수이며, 이 매개 변수를 지정하지 않으면 지원되는 최신 모델 버전이 선택됩니다.
results	LivenessWithVerifySessionResults	확인 세션을 사용한 활동성 결과입니다.
sessionId	string	이 세션을 참조할 고유 ID입니다.
status	OperationState	세션의 현재 상태입니다.

LivenessWithVerifySessionAttempt

세션 확인 시도가 있는 활동성입니다.

Name	형식	Description
attemptId	integer	시도 ID(1부터 시작)입니다.
attemptStatus	OperationState	시도의 상태입니다.
error	LivenessError	확인 호출이 있는 활동성 오류는 결과가 있는 경우 null이 됩니다.
result	LivenessWithVerifyResult	확인 호출을 사용한 활동성 결과는 오류가 있는 경우 null이 됩니다.

LivenessWithVerifySessionResults

확인 세션을 사용한 활동성 결과입니다.

Name	형식	Description
attempts	LivenessWithVerifySessionAttempt[]	세션에 대한 확인 호출을 사용하여 기본 활동성 데이터를 시도합니다.
verifyReferences	LivenessWithVerifyReference[]	얼굴 확인에 사용되는 참조입니다.

OperationState

세션의 현재 상태입니다.

Name	형식	Description
Canceled	string	사용자가 작업을 취소했습니다.
Failed	string	작업이 실패했습니다.
NotStarted	string	작업이 시작되지 않았습니다.
Running	string	작업이 진행 중입니다.
Succeeded	string	작업이 성공적으로 완료되었습니다.

QualityForRecognition

인식에 대한 이미지 품질을 나타냅니다.

Name	형식	Description
high	string	고품질.
low	string	품질이 낮습니다.
medium	string	중간 품질.

다음을 통해 공유

Liveness Session Operations - Create Liveness With Verify Session

URI 매개 변수

응답

보안

Ocp-Apim-Subscription-Key

AADToken

범위

예제

Create LivenessWithVerify Session

샘플 요청

샘플 응답

정의

FaceError

FaceErrorResponse

FaceRectangle

ImageType

LivenessColorDecisionTarget

LivenessDecision

LivenessDecisionTargets

LivenessError

LivenessModel

LivenessOperationMode

LivenessWithVerifyOutputs

LivenessWithVerifyReference

LivenessWithVerifyResult

LivenessWithVerifySession

LivenessWithVerifySessionAttempt

LivenessWithVerifySessionResults

OperationState

QualityForRecognition

추가 리소스