Liveness Session Operations - Create Liveness Session

服务:

Azure AI Services

API 版本:

v1.2

创建新的检测实时会话。
会话最适合客户端设备方案，开发人员希望授权客户端设备仅执行实时情况检测，而无需授予对其资源的完全访问权限。 创建的会话的生存期有限，并且仅授权客户端在访问过期之前执行所需的操作。

权限包括...

• • 能够调用 /detectLiveness/singleModal 进行最多 3 次重试。
  • 令牌生存期为 10 分钟。

注意

可以通过使用“删除生存期会话”操作删除会话来撤销客户端访问权限。 若要检索结果，请使用 Get Liveness 会话。 若要审核客户端对资源发出的单个请求，请使用列表 Liveness 会话审核条目。

POST {endpoint}/face/{apiVersion}/detectLiveness-sessions

URI 参数

名称	在	必需	类型	说明
apiVersion	path	True	string	API 版本
endpoint	path	True	string (uri)	支持的认知服务终结点（协议和主机名，例如：https://{resource-name}.cognitiveservices.azure.com）。

请求正文

名称	必需	类型	说明
livenessOperationMode	True	LivenessOperationMode	客户端应遵循的生存模式类型。
authTokenTimeToLiveInSeconds		integer (int32) minimum: 60 maximum: 86400	会话应持续到的秒数。 范围为 60 到 86400 秒。 默认值为 600。
deviceCorrelationId		string	每个最终用户设备的唯一 Guid。 这是提供速率限制和反锤击。 如果此请求中为“deviceCorrelationIdSetInClient”，则此“deviceCorrelationId”必须为 null。
deviceCorrelationIdSetInClient		boolean	是否允许客户端通过 Vision SDK 设置自己的“deviceCorrelationId”。 默认值为 false，并且必须在此请求正文中设置“deviceCorrelationId”。
enableSessionImage		boolean	是否存储会话映像。
livenessModelVersion		LivenessModel	用于实时分类的模型版本。 这是一个可选参数，如果未指定此参数，则将选择最新的受支持的模型版本

响应

名称	类型	说明
200 OK	LivenessSession	成功的调用为客户端设备创建会话，并提供授权令牌供客户端应用程序用于有限目的和时间。
Other Status Codes	FaceErrorResponse	意外的错误响应。 标头 x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

Azure AI 人脸订阅的密钥。

类型: apiKey
在: header

AADToken

Azure Active Directory OAuth2 流

类型: oauth2
流向: accessCode
授权 URL: https://api.example.com/oauth2/authorize
令牌 URL: https://api.example.com/oauth2/token

作用域

名称	说明
https://cognitiveservices.azure.com/.default

示例

Create Liveness Session

示例请求

HTTP

POST {endpoint}/face/v1.2/detectLiveness-sessions

{
  "livenessOperationMode": "Passive",
  "deviceCorrelationIdSetInClient": false,
  "deviceCorrelationId": "your_device_correlation_id",
  "authTokenTimeToLiveInSeconds": 60
}

示例响应

状态代码:

200

{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm",
  "status": "NotStarted",
  "modelVersion": "2024-11-15",
  "results": {
    "attempts": []
  }
}

定义

名称	说明
CreateLivenessSessionContent	用于创建实时会话的请求模型。
FaceError	错误对象。 有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含错误详细信息的响应。
FaceRectangle	在其中可以找到人脸的矩形。
LivenessColorDecisionTarget	用于实时分类的颜色图像中的目标。
LivenessDecision	生存度分类的结果。
LivenessDecisionTargets	用于生存度分类的目标。
LivenessError	生存度分类的错误。
LivenessModel	用于实时分类的模型版本。
LivenessOperationMode	用于驱动客户端最终用户体验的实时性操作模式。
LivenessResult	生存度分类的结果。
LivenessSession	检测生存期的会话结果。
LivenessSessionAttempt	实时会话尝试。
LivenessSessionResults	实时会话的结果。
OperationState	会话的当前状态。

CreateLivenessSessionContent

Object

用于创建实时会话的请求模型。

名称	类型	默认值	说明
authTokenTimeToLiveInSeconds	integer (int32) minimum: 60 maximum: 86400	600	会话应持续到的秒数。 范围为 60 到 86400 秒。 默认值为 600。
deviceCorrelationId	string		每个最终用户设备的唯一 Guid。 这是提供速率限制和反锤击。 如果此请求中为“deviceCorrelationIdSetInClient”，则此“deviceCorrelationId”必须为 null。
deviceCorrelationIdSetInClient	boolean		是否允许客户端通过 Vision SDK 设置自己的“deviceCorrelationId”。 默认值为 false，并且必须在此请求正文中设置“deviceCorrelationId”。
enableSessionImage	boolean		是否存储会话映像。
livenessModelVersion	LivenessModel		用于实时分类的模型版本。 这是一个可选参数，如果未指定此参数，则将选择最新的受支持的模型版本
livenessOperationMode	LivenessOperationMode		客户端应遵循的生存模式类型。

FaceError

Object

错误对象。 有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。

名称	类型	说明
code	string	服务器定义的错误代码集之一。
message	string	错误的人工可读表示形式。

FaceErrorResponse

Object

包含错误详细信息的响应。

名称	类型	说明
error	FaceError	错误对象。

FaceRectangle

Object

在其中可以找到人脸的矩形。

名称	类型	说明
height	integer (int32)	矩形的高度（以像素为单位）。
left	integer (int32)	如果图像到矩形左边缘（以像素为单位）的距离。
top	integer (int32)	图像到矩形上边缘（以像素为单位）的距离。
width	integer (int32)	矩形的宽度（以像素为单位）。

LivenessColorDecisionTarget

Object

用于实时分类的颜色图像中的目标。

名称	类型	说明
faceRectangle	FaceRectangle	进行活泼分类的人脸区域。

LivenessDecision

枚举

生存度分类的结果。

值	说明
realface	该算法已将目标人脸分类为真实。
spoofface	该算法已将目标人脸分类为欺骗。
uncertain	该算法无法将目标人脸分类为真实或欺骗。

LivenessDecisionTargets

Object

用于生存度分类的目标。

名称	类型	说明
color	LivenessColorDecisionTarget	用于实时分类的颜色图像中的目标。

LivenessError

Object

生存度分类的错误。

名称	类型	说明
code	string	错误代码。
message	string	错误消息。
targets	LivenessDecisionTargets	用于生存度分类的目标。

LivenessModel

枚举

用于实时分类的模型版本。

值	说明
2024-11-15

LivenessOperationMode

枚举

用于驱动客户端最终用户体验的实时性操作模式。

值	说明
Passive	利用被动实时技术，无需用户执行其他操作。 需要正常的室内照明和高屏幕亮度，以获得最佳性能。 因此，此模式具有较窄的操作信封，不适用于要求最终用户处于明亮照明条件的方案。 注意：这是移动解决方案（iOS 和 Android）解决方案唯一受支持的模式。
PassiveActive	此模式利用需要用户合作的混合被动或主动实时技术。 它经过优化，仅在欠佳的照明条件下需要主动运动。 与被动模式不同，此模式没有照明限制，因此提供更广泛的操作信封。 由于浏览器上缺少自动屏幕亮度控制，阻碍被动模式在基于 Web 的解决方案上的操作信封，此模式更可取于基于 Web 的解决方案。

LivenessResult

Object

生存度分类的结果。

名称	类型	说明
digest	string	此请求的服务器计算摘要。 如果客户端报告的摘要与服务器计算摘要不同，则客户端和服务之间的消息完整性已泄露，因此不应信任结果。 有关详细信息，请参阅有关如何利用此值来保护端到端解决方案的指南。
livenessDecision	LivenessDecision	目标人脸的活度分类。
sessionImageId	string	会话请求的图像 ID。
targets	LivenessDecisionTargets	用于生存度分类的目标。

LivenessSession

Object

检测生存期的会话结果。

名称	类型	说明
authToken	string	持有者令牌，用于为客户端应用程序上运行的视觉 SDK 提供身份验证。 此持有者令牌具有有限的权限，只能执行所需的操作，并在 TTL 时间后过期。 它也是可审核的。
modelVersion	LivenessModel	用于实时分类的模型版本。 这是一个可选参数，如果未指定此参数，则将选择最新的受支持的模型版本
results	LivenessSessionResults	实时会话的结果。
sessionId	string	要引用此会话的唯一 ID。
status	OperationState	会话的当前状态。

LivenessSessionAttempt

Object

实时会话尝试。

名称	类型	说明
attemptId	integer (int32)	尝试 ID，从 1 开始。
attemptStatus	OperationState	尝试的状态。
error	LivenessError	如果存在结果，则实时调用的错误将为 null。
result	LivenessResult	如果出现错误，则实时调用的结果将为 null。

LivenessSessionResults

Object

实时会话的结果。

名称	类型	说明
attempts	LivenessSessionAttempt[]	尝试使用会话调用基础实时性的数据。

OperationState

枚举

会话的当前状态。

值	说明
Canceled	该操作已被用户取消。
Failed	操作失败。
NotStarted	操作尚未启动。
Running	操作正在进行中。
Succeeded	操作已成功完成。