1. 接口描述
接口请求域名： faceid.tencentcloudapi.com 。
传入视频和身份信息，先判断视频中是否为真人，判断为真人后，再判断该视频中的人与权威库的证件照是否属于同一个人。
默认接口请求频率限制：100次/秒。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：LivenessRecognition。 |
| Version | 是 | String | 公共参数，本接口取值：2018-03-01。 |
| Region | 否 | String | 公共参数，此参数为可选参数。 |
| IdCard | 是 | String | 身份证号 示例值：11204416541220243X |
| Name | 是 | String | 姓名。中文请使用UTF-8编码。 示例值：韦小宝 |
| LivenessType | 是 | String | 活体检测类型，取值：LIP/ACTION/SILENT。 LIP为数字模式，ACTION为动作模式，SILENT为静默模式，三种模式选择一种传入。 示例值：SILENT |
| VideoBase64 | 否 | String | 用于活体检测的视频，视频的BASE64值； BASE64编码后的大小不超过8M，支持mp4、avi、flv格式。 示例值： |
| VideoUrl | 否 | String | 用于活体检测的视频Url 地址。视频下载后经Base64编码不超过 8M，视频下载耗时不超过4S，支持mp4、avi、flv格式。 视频的 VideoUrl、VideoBase64 必须提供一个，如果都提供，只使用 VideoBase64。 建议视频存储于腾讯云的 Url 可保障更高的下载速度和稳定性，建议视频存储于腾讯云。非腾讯云存储的 Url 速度和稳定性可能受一定影响。 |
| ValidateData | 否 | String | 数字模式传参：传数字验证码，验证码需先调用获取数字验证码接口得到； 动作模式传参：传动作顺序，动作顺序需先调用获取动作顺序接口得到； 静默模式传参：空。 示例值：1234 |
| Optional | 否 | String | 额外配置，传入JSON字符串。 { "BestFrameNum": 2 //需要返回多张最佳截图，取值范围2-10 } 示例值：{} |
| Encryption | 否 | Encryption | 敏感数据加密信息。对传入信息（姓名、身份证号）有加密需求的用户可使用此参数，详情请点击左侧链接。 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| BestFrameBase64 | String | 验证通过后的视频最佳截图照片，照片为BASE64编码后的值，jpg格式。 注意：此字段可能返回 null，表示取不到有效值。 示例值： |
| Sim | Float | 相似度，取值范围 [0.00, 100.00]。推荐相似度大于等于70时可判断为同一人，可根据具体场景自行调整阈值（阈值70的误通过率为千分之一，阈值80的误通过率是万分之一） 示例值：89.88 |
| Result | String | 业务错误码，成功情况返回Success, 错误情况请参考下方错误码 列表中FailedOperation部分 示例值：Success |
| Description | String | 业务结果描述。 示例值：成功 |
| BestFrameList | Array of String | 最佳截图列表，仅在配置了返回多张最佳截图时返回。 注意：此字段可能返回 null，表示取不到有效值。 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 静默活体人脸核身
输入示例
POST / HTTP/1.1
Host: faceid.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: LivenessRecognition
<公共请求参数>
{
"IdCard": "11204416541220243X",
"LivenessType": "SILENT",
"Name": "韦小宝",
"VideoBase64": "<VideoBase64>"
}输出示例
{
"Response": {
"Result": "Success",
"Description": "成功",
"BestFrameBase64": "<Imagebase64>",
"BestFrameList": [
"123"
],
"Sim": 89.88,
"RequestId": "f904f4cf-75db-4f8f-a5ec-dc4f942c7f7a"
}
}5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| 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.CompareLibServiceUnavailable | 比对库源维护中，暂时不可用 |
| FailedOperation.CompareLowSimilarity | 比对相似度未达到通过标准。 |
| FailedOperation.CompareSystemError | 调用比对引擎接口出错。 |
| FailedOperation.DecryptSystemError | 解密失败。 |
| FailedOperation.DownLoadError | 文件下载失败。 |
| FailedOperation.DownLoadTimeoutError | 文件下载超时。 |
| FailedOperation.IdFormatError | 输入的身份证号有误。 |
| FailedOperation.IdNameMisMatch | 姓名和身份证号不一致，请核实后重试。 |
| FailedOperation.IdNoExistSystem | 库中无此号，请到户籍所在地进行核实。 |
| FailedOperation.IdPhotoNoExist | 库中无此号照片，请到户籍所在地进行核实。 |
| FailedOperation.IdPhotoPoorQuality | 证件图片质量差，请更新后重试。 |
| FailedOperation.IdentityAuthLimitExceeded | 姓名/身份证号认证次数超过当日限制，请次日重试 |
| FailedOperation.LifePhotoDetectFaces | 检测到多张人脸。 |
| FailedOperation.LifePhotoDetectFake | 实人比对没通过。 |
| FailedOperation.LifePhotoDetectNoFaces | 未能检测到完整人脸。 |
| 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.NameFormatError | 输入的姓名有误。 |
| FailedOperation.SilentDetectFail | 实人检测失败。 |
| FailedOperation.SilentThreshold | 实人检测未达到通过标准。 |
| FailedOperation.SilentTooShort | 视频录制时间过短，请录制2秒以上的视频。 |
| FailedOperation.StsUnAuthErrError | STS未授权。 |
| FailedOperation.UnKnown | 内部未知错误。 |
| InvalidParameter | 参数错误。 |
| InvalidParameter.UnsupportEncryptField | 存在不加密的字段，请参考文档修改。 |
| InvalidParameterValue | 参数取值错误。 |
| UnauthorizedOperation | 未授权操作。 |
| UnauthorizedOperation.Arrears | 账号已欠费。 |
| UnauthorizedOperation.NonAuthorize | 账号未实名。 |
| UnauthorizedOperation.Nonactivated | 未开通服务。 |
| UnsupportedOperation | 操作不支持。 |
