Liveness Session Operations - Get Liveness Session Result

Reference

Service:: Azure AI Services

API Version:: v1.2-preview.1

Get session result of detectLiveness/singleModal call.

GET {endpoint}/face/{apiVersion}/detectLiveness/singleModal/sessions/{sessionId}

URI Parameters

Name	In	Required	Type	Description
apiVersion	path	True	string	API Version
endpoint	path	True	string uri	Supported Cognitive Services endpoints (protocol and hostname, for example: https://{resource-name}.cognitiveservices.azure.com).
sessionId	path	True	string	The unique ID to reference this session.

Responses

Name	Type	Description
200 OK	LivenessSession	The request has succeeded.
Other Status Codes	FaceErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

LivenessSession

The request has succeeded.

Other Status Codes

FaceErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

The secret key for your Azure AI Face subscription.

Type: apiKey
In: header

AADToken

The Azure Active Directory OAuth2 Flow

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

Scopes

Name	Description
https://cognitiveservices.azure.com/.default

Examples

Get LivenessSession Result

Sample request

HTTP

GET {endpoint}/face/v1.2-preview.1/detectLiveness/singleModal/sessions/b12e033e-bda7-4b83-a211-e721c661f30e

Sample response

Status code:: 200

{
  "id": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "createdDateTime": "2024-03-05T11:07:29.698Z",
  "sessionStartDateTime": "2024-03-05T11:07:29.698Z",
  "sessionExpired": true,
  "deviceCorrelationId": "your_device_correlation_id",
  "authTokenTimeToLiveInSeconds": 600,
  "status": "NotStarted",
  "result": {
    "id": 4,
    "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
    "requestId": "4af681e9-0e25-43e9-9922-a7adebf13b2f",
    "clientRequestId": "4af681e9-0e25-43e9-9922-a7adebf13b2f",
    "receivedDateTime": "2024-03-05T11:07:29.698Z",
    "request": {
      "url": "/face/v1.2-preview.1/detectliveness/singlemodal",
      "method": "POST",
      "contentLength": 18,
      "contentType": "multipart/form-data",
      "userAgent": "Mozilla/5.0 (Linux) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Mobile Safari/537.36"
    },
    "response": {
      "body": {},
      "statusCode": 200,
      "latencyInMilliseconds": 1200
    },
    "digest": "1CC98BA83EAF1D0FF7F566FAEFCCCC787819FFA01251E2D9299143F7AD6651DB"
  }
}

Definitions

Name	Description
AuditLivenessResponseInfo	Audit entry for a response in the session.
AuditRequestInfo	Audit entry for a request in the session.
FaceError	The error object. For comprehensive details on error codes and messages returned by the Face Service, please refer to the following link: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	A response containing error details.
FaceRectangle	A rectangle within which a face can be found.
FaceSessionStatus	The current status of the session.
ImageType	The type of image.
LivenessDecision	The outcome of the liveness classification.
LivenessModel	The model version used for liveness classification.
LivenessOutputsTarget	The liveness classification for target face.
LivenessResponseBody	The response body of detect liveness API call.
LivenessSession	Session result of detect liveness.
LivenessSessionAuditEntry	Audit entry for a request in session.
LivenessWithVerifyImage	The detail of face for verification.
LivenessWithVerifyOutputs	The face verification output.
QualityForRecognition	Indicates quality of image for recognition.

AuditLivenessResponseInfo

Audit entry for a response in the session.

Name	Type	Description
body	LivenessResponseBody	The response body. The schema of this field will depend on the request.url and request.method used by the client.
latencyInMilliseconds	integer	The server measured latency for this request in milliseconds.
statusCode	integer	The HTTP status code returned to the client.

AuditRequestInfo

Audit entry for a request in the session.

Name	Type	Description
contentLength	integer	The length of the request body in bytes.
contentType	string	The content type of the request.
method	string	The HTTP method of the request (i.e., GET, POST, DELETE).
url	string	The relative URL and query of the liveness request.
userAgent	string	The user agent used to submit the request.

FaceError

The error object. For comprehensive details on error codes and messages returned by the Face Service, please refer to the following link: https://aka.ms/face-error-codes-and-messages.

Name	Type	Description
code	string	One of a server-defined set of error codes.
message	string	A human-readable representation of the error.

FaceErrorResponse

A response containing error details.

Name	Type	Description
error	FaceError	The error object.

FaceRectangle

A rectangle within which a face can be found.

Name	Type	Description
height	integer	The height of the rectangle, in pixels.
left	integer	The distance from the left edge if the image to the left edge of the rectangle, in pixels.
top	integer	The distance from the top edge if the image to the top edge of the rectangle, in pixels.
width	integer	The width of the rectangle, in pixels.

FaceSessionStatus

The current status of the session.

Name	Type	Description
NotStarted	string	Session has not started.
ResultAvailable	string	Session has available result.
Started	string	Session has started.

ImageType

The type of image.

Name	Type	Description
Color	string	Color image.
Depth	string	Depth image.
Infrared	string	Infrared image.

LivenessDecision

The outcome of the liveness classification.

Name	Type	Description
realface	string	The algorithm has classified the target face as real.
spoofface	string	The algorithm has classified the target face as a spoof.
uncertain	string	The algorithm could not classify the target face as either real or spoof.

LivenessModel

The model version used for liveness classification.

Name	Type	Description
2022-10-15-preview.04	string
2023-12-20-preview.06	string

LivenessOutputsTarget

The liveness classification for target face.

Name	Type	Description
faceRectangle	FaceRectangle	The face region where the liveness classification was made on.
fileName	string	The file name which contains the face rectangle where the liveness classification was made on.
imageType	ImageType	The image type which contains the face rectangle where the liveness classification was made on.
timeOffsetWithinFile	integer	The time offset within the file of the frame which contains the face rectangle where the liveness classification was made on.

LivenessResponseBody

The response body of detect liveness API call.

Name	Type	Description
livenessDecision	LivenessDecision	The liveness classification for the target face.
modelVersionUsed	LivenessModel	The model version used for liveness classification.
target	LivenessOutputsTarget	Specific targets used for liveness classification.
verifyResult	LivenessWithVerifyOutputs	The face verification output. Only available when the request is liveness with verify.