Liveness Session Operations - Get Liveness With Verify Session Audit Entries

Service:

Azure AI Services

API Version:

v1.1-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

HTTP

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

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.