Liveness Session Operations - Get Liveness With Verify Session Audit Entries

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

Gets session requests and response body for the session.

GET {endpoint}/face/{apiVersion}/detectLivenessWithVerify/singleModal/sessions/{sessionId}/audit
With optional parameters: 
GET {endpoint}/face/{apiVersion}/detectLivenessWithVerify/singleModal/sessions/{sessionId}/audit?start={start}&top={top}

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.
start
 query

string

List resources greater than the "start". It contains no more than 64 characters. Default is empty.
top
 query

integer

int32

The number of items to list, ranging in [1, 1000]. Default is 1000.

Responses

Name Type Description
200 OK

LivenessSessionAuditEntry[]

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 Audit Entries

Sample request

GET {endpoint}/face/v1.2-preview.1/detectLivenessWithVerify/singleModal/sessions/b12e033e-bda7-4b83-a211-e721c661f30e/audit?start=0&top=20

Sample response

Status code:
200 
[
  {
    "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.
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.
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.

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.

QualityForRecognition

Indicates quality of image for recognition.

Name Type Description
high

string

High quality.
low

string

Low quality.
medium

string

Medium quality.