接口请求域名： faceid.intl.tencentcloudapi.com 。
传入视频和照片，先判断视频中是否为真人，判断为真人后，再判断该视频中的人与上传照片是否属于同一个人。
老版本接口我们仍继续维护，但不支持新客户开通调用，建议您使用VideoLivenessCompare，体验更优服务。
默认接口请求频率限制：100次/秒。
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：LivenessCompare。 |
| Version | 是 | String | 公共参数，本接口取值：2018-03-01。 |
| Region | 否 | String | 公共参数，此参数为可选参数。 |
| LivenessType | 是 | String | 活体检测类型。
|
| ImageBase64 | 否 | String | 用于人脸比对的照片的Base64值。
|
| ImageUrl | 否 | String | 用于人脸比对照片的URL地址。
|
| ValidateData | 否 | String | 数字模式传参：传数字验证码，需自定义四位数字验证码； 动作模式传参：传动作顺序，需自定义动作顺序(2,1 or 1,2)； 静默模式传参：空。 |
| Optional | 否 | String | 额外配置，传入JSON字符串。
|
| VideoBase64 | 否 | String | 用于活体检测的视频，视频的Base64值。
|
| VideoUrl | 否 | String | 用于活体检测的视频Url 地址。
|
| 参数名称 | 类型 | 描述 |
|---|---|---|
| BestFrameBase64 | String | 验证通过后的视频最佳截图照片。
注意：此字段可能返回 null，表示取不到有效值。 |
| Sim | Float | 相似度。- 取值范围 [0.00, 100.00]。- 推荐相似度大于等于70时可判断为同一人（采用固定阈值70，误通过率为万分之一，不支持调整阈值）。 |
| Result | String | 业务错误码。
|
| Description | String | 业务结果描述。 |
| BestFrameList | Array of String | 最佳截图列表。
注意：此字段可能返回 null，表示取不到有效值。 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
POST / HTTP/1.1
Host: faceid.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: LivenessCompare
<公共请求参数>
{
"LivenessType": "SILENT",
"ImageBase64": "/9j/4AAQSk...GArFYH/9k=",
"VideoBase64": "AAAAIGZ0eX...cBQCKAowc="
}
{
"Response": {
"BestFrameBase64": "/9j/4AAQSk...RgkelAH//Z",
"BestFrameList": [],
"Description": "实人检测失败",
"RequestId": "09fe2045-af63-43d5-8d7a-d9f7834ca62e",
"Result": "FailedOperation.SilentDetectFail",
"Sim": 0
}
}
POST / HTTP/1.1
Host: faceid.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: LivenessCompare
<公共请求参数>
{
"LivenessType": "SILENT",
"ImageBase64": "/9j/4AAQSk...GArFYH/9k=",
"VideoBase64": "AAAAIGZ0eX...cBQCKAowc="
}
{
"Response": {
"Result": "Success",
"Description": "成功",
"BestFrameBase64": "/9j/4AAQSk...W8+nU//9k=",
"BestFrameList": [
"/9j/4AAQSk...px72+8/9k="
],
"Sim": 89.88,
"RequestId": "f904f4cf-75db-4f8f-a5ec-dc4f942c7f7a"
}
}
云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| AuthFailure.InvalidAuthorization | CAM签名/鉴权错误。 |
| FailedOperation.ActionCloseEye | 未检测到闭眼动作。 |
| FailedOperation.ActionFaceClose | 脸离屏幕太近。 |
| FailedOperation.ActionFaceFar | 脸离屏幕太远。 |
| FailedOperation.ActionFaceLeft | 脸离屏幕太左。 |
| FailedOperation.ActionFaceRight | 脸离屏幕太右。 |
| FailedOperation.ActionFirstAction | 未检测到动作配合。 |
| FailedOperation.ActionLightDark | 光线太暗。 |
| FailedOperation.ActionLightStrong | 光线太强。 |
| FailedOperation.ActionNodetectFace | 未能检测到完整人脸。 |
| FailedOperation.ActionOpenMouth | 未检测到张嘴动作。 |
| FailedOperation.CompareFail | 比对失败。 |
| FailedOperation.CompareLowSimilarity | 比对相似度未达到通过标准。 |
| FailedOperation.CompareSystemError | 调用比对引擎接口出错。 |
| FailedOperation.CompressVideoError | The video compression failed. Please try again or reduce the size of the input video. |
| FailedOperation.DownLoadError | 文件下载失败。 |
| FailedOperation.DownLoadTimeoutError | 文件下载超时。 |
| FailedOperation.LifePhotoDetectFaces | 检测到多张人脸。 |
| FailedOperation.LifePhotoDetectFake | 实人比对没通过。 |
| FailedOperation.LifePhotoDetectNoFaces | 未能检测到完整人脸。 |
| FailedOperation.LifePhotoPoorQuality | 传入图片分辨率太低，请重新上传。 |
| FailedOperation.LifePhotoSizeError | 传入图片过大或过小。 |
| FailedOperation.LipFaceIncomplete | 脸部未完整露出。 |
| FailedOperation.LipMoveSmall | 嘴唇动作幅度过小。 |
| FailedOperation.LipNetFailed | 视频拉取失败，请重试。 |
| FailedOperation.LipSizeError | 视频为空，或大小不合适，请控制录制时长在6s左右。 |
| FailedOperation.LipVideoInvalid | 视频格式有误。 |
| FailedOperation.LipVideoQuaility | 视频像素太低。 |
| FailedOperation.LipVoiceDetect | 未检测到声音。 |
| FailedOperation.LipVoiceLow | 视频声音太小。 |
| FailedOperation.LipVoiceRecognize | 声音识别失败。 |
| FailedOperation.LivessBestFrameError | 人脸检测失败，无法提取比对照。 |
| FailedOperation.LivessDetectFail | 活体检测没通过。 |
| FailedOperation.LivessDetectFake | 疑似非真人录制。 |
| FailedOperation.LivessSystemError | 调用活体引擎接口出错。 |
| FailedOperation.LivessUnknownError | 视频实人检测没通过。 |
| FailedOperation.SilentDetectFail | 实人检测失败。 |
| FailedOperation.SilentEyeLiveFail | 眼睛检测失败。 |
| FailedOperation.SilentFaceDetectFail | 视频未检测到人脸。 |
| FailedOperation.SilentFaceQualityFail | 视频中人脸质量低。 |
| FailedOperation.SilentFaceWithMaskFail | 检测到带口罩。 |
| FailedOperation.SilentMouthLiveFail | 嘴巴检测失败。 |
| FailedOperation.SilentMultiFaceFail | 视频检测中有多个人脸。 |
| FailedOperation.SilentPictureLiveFail | 疑似翻拍。 |
| FailedOperation.SilentThreshold | 实人检测未达到通过标准。 |
| FailedOperation.SilentTooShort | 视频录制时间过短，请录制2秒以上的视频。 |
| FailedOperation.UnKnown | 内部未知错误。 |
| InvalidParameter | 参数错误。 |
| InvalidParameterValue | 参数取值错误。 |
| UnauthorizedOperation | 未授权操作。 |
| UnauthorizedOperation.Arrears | 账号已欠费。 |
| UnauthorizedOperation.NonAuthorize | 账号未实名。 |
| UnauthorizedOperation.Nonactivated | 未开通服务。 |
| UnsupportedOperation | 操作不支持。 |
文档反馈