Share via

Liveness Session Operations - Get Liveness With Verify Session Result

  • Reference
Service:
Azure AI Services
API Version:
v1.2-preview.1

Get session result of detectLivenessWithVerify/singleModal call.

GET {endpoint}/face/{apiVersion}/detectLivenessWithVerify/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

LivenessWithVerifySession

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 LivenessWithVerify Session Result

Sample request

GET {endpoint}/face/v1.2-preview.1/detectLivenessWithVerify/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.
LivenessSessionAuditEntry

Audit entry for a request in session.
LivenessWithVerifyImage

The detail of face for verification.
LivenessWithVerifyOutputs

The face verification output.
LivenessWithVerifySession

Session result of detect liveness with verify.
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.

LivenessSessionAuditEntry

Audit entry for a request in session.

Name Type Description
clientRequestId

string

The unique clientRequestId that is sent by the client in the 'client-request-id' header.
digest

string

The server calculated digest for this request. If the client reported digest differs from the server calculated digest, then the message integrity between the client and service has been compromised and the result should not be trusted. For more information, see how to guides on how to leverage this value to secure your end-to-end solution.
id

integer

The unique id to refer to this audit request. Use this id with the 'start' query parameter to continue on to the next page of audit results.
receivedDateTime

string

The UTC DateTime that the request was received.
request

AuditRequestInfo

The request of this entry.
requestId

string

The unique requestId that is returned by the service to the client in the 'apim-request-id' header.
response

AuditLivenessResponseInfo

The response of this entry.
sessionId

string

The unique sessionId of the created session. It will expire 48 hours after it was created or may be deleted sooner using the corresponding session DELETE operation.
sessionImageId

string

The image ID of the session request.
verifyImageHash

string

The sha256 hash of the verify-image in the request.

LivenessWithVerifyImage

The detail of face for verification.

Name Type Description
faceRectangle

FaceRectangle

The face region where the comparison image's classification was made.
qualityForRecognition

QualityForRecognition

Quality of face image for recognition.

LivenessWithVerifyOutputs

The face verification output.

Name Type Description
isIdentical

boolean

Whether the target liveness face and comparison image face match.
matchConfidence

number

The target face liveness face and comparison image face verification confidence.
verifyImage

LivenessWithVerifyImage

The detail of face for verification.

LivenessWithVerifySession

Session result of detect liveness with verify.

Name Type Default value Description
authTokenTimeToLiveInSeconds

integer

600

Seconds the session should last for. Range is 60 to 86400 seconds. Default value is 600.
createdDateTime

string

DateTime when this session was created.
deviceCorrelationId

string

Unique Guid per each end-user device. This is to provide rate limiting and anti-hammering. If 'deviceCorrelationIdSetInClient' is true in this request, this 'deviceCorrelationId' must be null.
id

string

The unique ID to reference this session.
result

LivenessSessionAuditEntry

The latest session audit result only populated if status == 'ResultAvailable'.
sessionExpired

boolean

Whether or not the session is expired.
sessionStartDateTime

string

DateTime when this session was started by the client.
status

FaceSessionStatus

The current status of the session.

QualityForRecognition

Indicates quality of image for recognition.

Name Type Description
high

string

High quality.
low

string

Low quality.
medium

string

Medium quality.