Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

StartFaceLivenessSession

Starts a Face Liveness video stream and liveness detection process for a given session.

Requires sessionId, ChallengeVersions, VideoWidth, VideoHeight and a RequestEventStream as input. The event stream contains information about different events for the session, including the challenge information used for verification.

The maximum video size for Face Liveness is 10 MB. Face Liveness throws a ValidationException if the video does not match the necessary formatting and size parameters.

StartFaceLivenessSession supports the websockets and the AWS SDK for JavaScript.

Request Syntax


POST /start-face-liveness-session HTTP/1.1
x-amz-rekognition-streaming-liveness-session-id: SessionId
x-amz-rekognition-streaming-liveness-video-width: VideoWidth
x-amz-rekognition-streaming-liveness-video-height: VideoHeight
x-amz-rekognition-streaming-liveness-challenge-versions: ChallengeVersions
Content-type: application/json

{
   "ClientSessionInformationEvent": { 
      "Challenge": { ... }
   },
   "VideoEvent": { 
      "TimestampMillis": number,
      "VideoChunk": blob
   }
}

URI Request Parameters

The request uses the following URI parameters.

ChallengeVersions

String containing comma separated list of challenge versions supported by client.

Length Constraints: Minimum length of 15. Maximum length of 150.

Pattern: ^([a-zA-Z]{10,}_\d+\.\d+\.\d+){1}(,[a-zA-Z]{10,}_\d+\.\d+\.\d+)*

Required: Yes

SessionId

A unique 128-bit UUID. Used to uniquely identify the session and also acta as an idempotency token for all operations associated with the session.

Length Constraints: Fixed length of 36.

Pattern: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

Required: Yes

VideoHeight

The height of the video object included in a request to start a Face Liveness session.

Length Constraints: Minimum length of 3. Maximum length of 4.

Pattern: ^[0-9]{3,}$

Required: Yes

VideoWidth

The width of the video object included in a request to start a Face Liveness session.

Length Constraints: Minimum length of 3. Maximum length of 4.

Pattern: ^[0-9]{3,}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

ClientSessionInformationEvent

Information event for the client session for a given Face Liveness request stream.

Type: ClientSessionInformationEvent object

Required: No

VideoEvent

Contains video events for a Face Liveness request stream.

Type: VideoEvent object

Required: No

Response Syntax


HTTP/1.1 200
x-amz-rekognition-streaming-liveness-session-id: SessionId
Content-type: application/json

{
   "DisconnectionEvent": { 
      "TimestampMillis": number
   },
   "InternalServerException": { 
   },
   "ServerSessionInformationEvent": { 
      "SessionInformation": { 
         "Challenge": { ... }
      }
   },
   "ServiceQuotaExceededException": { 
   },
   "ServiceUnavailableException": { 
   },
   "ThrottlingException": { 
   },
   "ValidationException": { 
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

SessionId

The ID that identifies a Face Liveness session.

Length Constraints: Fixed length of 36.

Pattern: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

The following data is returned in JSON format by the service.

DisconnectionEvent

Notification that disconnection event has occurred to a Face Liveness session.

Type: DisconnectionEvent object

InternalServerException

Notification that an InternalServerException occurred during a Face Liveness session.

Type: Exception

HTTP Status Code: 500

ServerSessionInformationEvent

Details for a server session information event.

Type: ServerSessionInformationEvent object

ServiceQuotaExceededException

Notification that a ServiceQuotaExceededException occurred during a Face Liveness session.

Type: Exception

HTTP Status Code: 429

ServiceUnavailableException

Notification that a ServiceUnavailableException occurred during a Face Liveness session.

Type: Exception

HTTP Status Code: 503

ThrottlingException

Notification that a ThrottlingException occurred during a Face Liveness session.

Type: Exception

HTTP Status Code: 429

ValidationException

Notification that a ValidationException occurred during a Face Liveness session.

Type: Exception

HTTP Status Code: 400

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

Occurs when the client isn't authorized to perform the action.

HTTP Status Code: 403

InternalServerException

Unexpected error during processing of request.

HTTP Status Code: 500

ServiceQuotaExceededException

Occurs when a request would cause a service quota to be exceeded.

HTTP Status Code: 429

ServiceUnavailableException

Service-wide throttling to recover from an operational event or service is not able to scale.

HTTP Status Code: 503

SessionNotFoundException

Occurs when the given sessionId is not found.

HTTP Status Code: 400

ThrottlingException

A request was denied due to request throttling. Occurs when too many requests were made by a user (exceeding their service quota), the service isn't able to scale, or a service-wide throttling was done to recover from an operational event.

HTTP Status Code: 429

ValidationException

The input fails to satisfy the constraints specified by the service. Potential reasons inlcude: video quality or size is invalid, video container format not supported, video does not have enough information - no person detected in video, request couldn't be parsed or is invalid, session has expired or is invalid, S3 bucket is invalid/in another AWS region, KMS Key is invalid.

HTTP Status Code: 400