接口请求域名： faceid.intl.tencentcloudapi.com 。
本接口支持判断真人以及照片比对，以在线验证用户的身份。通过在接口中传入视频和照片，它将先判断视频中是否为真人，判断为真人后，再判断该视频中的人与上传照片是否属于同一个人，返回认证结果。
默认接口请求频率限制：20次/秒。
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：CompareFaceLiveness。 |
| Version | 是 | String | 公共参数，本接口取值：2018-03-01。 |
| Region | 是 | String | 公共参数，详见产品支持的 地域列表，本接口仅支持其中的: ap-bangkok, ap-hongkong, ap-singapore 。 |
| ImageBase64 | 是 | String | 用于人脸比对的照片的Base64值。 - Base64编码后的图片数据大小不超过3M，仅支持jpg、png格式。 - 请使用标准的Base64编码方式(带=补位)，编码规范参考RFC4648。 |
| VideoBase64 | 是 | String | 用于活体检测的视频，视频的Base64值。 - Base64编码后的大小不超过8M，支持mp4、avi、flv格式。 - 请使用标准的Base64编码方式(带=补位)，编码规范参考RFC4648。 |
| LivenessType | 是 | String | 活体检测类型。 - 取值范围： ACTION为动作模式。 SILENT为静默模式。 - 两种模式选择一种传入。 |
| ValidateData | 否 | String | 控制动作顺序，动作类型有以下几种： 1（张嘴）2（眨眼）3（点头）4（摇头） 支持动作四选一或四选二 。 - 当LivenessType参数取值为ACTION时，必填。 - 单动传参示例："1" 。 - 多动作传参示例："4,2" 。 - 当LivenessType参数取值为SILENT时，留空。 |
| 参数名称 | 类型 | 描述 |
|---|---|---|
| Result | String | 业务错误码。 - 当返回值为“Success”时，表示活体检测以及人脸比对通过，判定为同一人。 - 当返回值为"FailedOperation.CompareLowSimilarity"时，表示活体检测通过，人脸比对相似度低于70分，判定不是同一人。 - 其他错误情况请参考 活体人脸比对（纯API）错误码 |
| Description | String | 业务结果描述。 |
| Sim | Float | 该值表示人脸比对相似度，取值范围 [0.00, 100.00]。 - 阈值70的误通过率为千分之一，阈值80的误通过率是万分之一。 - 当Result参数取值为"Success"或者"FailedOperation.CompareLowSimilarity"时，该值有效。 |
| BestFrameBase64 | String | 验证通过后的视频最佳截图照片，照片为BASE64编码后的值，jpg格式。 注意：此字段可能返回 null，表示取不到有效值。 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
活体检测以及人脸比对通过，判定为同一人。
POST / HTTP/1.1
Host: faceid.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CompareFaceLiveness
<公共请求参数>
{
"LivenessType": "SILENT",
"ImageBase64": "iVBORw0KGg...s97n//2Q==",
"VideoBase64": "AAAAGGZ0eX...AAwAAAAEecg=",
"ValidateData": ""
}
{
"Response": {
"Result": "Success",
"Description": "Success",
"Sim": 100,
"BestFrameBase64": "/9j/4AAQSk...s97n//2Q==",
"RequestId": "f89097ac-4003-4d73-acb3-696d4057b9eb"
}
}
活体检测以及人脸比对通过，判定不是同一人。
POST / HTTP/1.1
Host: faceid.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CompareFaceLiveness
<公共请求参数>
{
"ImageBase64": "iVBORw0KGg...s97n//2Q==",
"VideoBase64": "AAAAGGZ0eX...AAwAAAAEecg=",
"LivenessType": "ACTION",
"ValidateData": "1"
}
{
"Response": {
"Result": "FailedOperation.CompareLowSimilarity",
"Description": "The comparison similarity did not reach the passing standard.",
"Sim": 9.21,
"BestFrameBase64": "/9j/4AAQSk...8ASrH/2Q==",
"RequestId": "6176fad1-f078-445b-8a4d-c8a903528b5a"
}
}
活体检测失败，没有检测到指定动作。
POST / HTTP/1.1
Host: faceid.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CompareFaceLiveness
<公共请求参数>
{
"ImageBase64": "iVBORw0KGg...s97n//2Q==",
"VideoBase64": "AAAAGGZ0eX...AAwAAAAEecg=",
"LivenessType": "ACTION",
"ValidateData": "4,2"
}
{
"Response": {
"Result": "FailedOperation.ActionFirstAction",
"Description": "The first motion is not detected.",
"Sim": 0,
"BestFrameBase64": "/9j/4AAQSk...W/M7/M/9k=",
"RequestId": "df5afd82-6469-4a4a-bd62-debf8c2ef94f"
}
}
云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| FailedOperation.CompressVideoError | The video compression failed. Please try again or reduce the size of the input video. |
| FailedOperation.UnKnown | 内部未知错误。 |
| InvalidParameter | 参数错误。 |
| InvalidParameterValue | 参数取值错误。 |
| UnauthorizedOperation.Activating | 服务开通中。 |
| UnauthorizedOperation.Arrears | 账号已欠费。 |
| UnauthorizedOperation.NonAuthorize | 账号未实名。 |
| UnauthorizedOperation.Nonactivated | 未开通服务。 |
文档反馈