数据万象活体人脸核身-API 文档-文档中心-腾讯云

功能描述
集成了活体检测和跟权威库进行比对的能力，传入一段视频和姓名、身份证号信息即可进行验证。对录制的自拍视频进行活体检测，从而确认当前用户为真人，可防止照片、视频、静态3D建模等各种不同类型的攻击。检测为真人后，再判断该视频中的人与权威库的证件照是否属于同一个人，实现用户身份信息核实。
注意：
该功能目前仅提供 API 使用方式。
授权说明
通过子账号使用时，需要授予ci:CreateLivenessRecognitionJob权限，详情请参见 数据万象 action。
服务开通
使用该功能需提前开通数据万象，并绑定存储桶。详情请参见 绑定存储桶。
使用限制
使用该接口时，请先确认相关限制条件。详情请参见 使用限制。
用于活体检测的视频 BASE64 编码后的大小不超过8M，支持 mp4、avi、flv 格式。
费用说明
该接口为付费服务，产生的费用将由数据万象收取，详细计费说明可参见 内容识别费用。
﻿
请求
上传时处理
视频上传时检测的请求包与 COS 简单上传文件接口一致，只需增加相关处理参数，即可在视频上传时返回检测结果，并可将原视频存入到 COS。
PUT /<ObjectKey>?ci-process=LivenessRecognition&IdCard=<IdCard>&Name=<Name>&LivenessType=<LivenessType> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
﻿
说明
Authorization: Auth String，详情请参见 请求签名 文档。
云上数据处理
云上数据处理请求能够对已存储在 COS 的人脸视频进行相应识别操作，返回检测结果。
GET /<ObjectKey>?ci-process=LivenessRecognition&IdCard=<IdCard>&Name=<Name>&LivenessType=<LivenessType> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
﻿
说明
Authorization: Auth String，详情请参见 请求签名 文档。
请求参数
参数名称
描述
类型
是否必选
ObjectKey
对象文件名，例如：folder/document.mp4，BASE64 编码后的大小不超过8M，支持 mp4、avi、flv 格式
String
是
ci-process
数据万象处理能力，人脸核身固定为 LivenessRecognition
String
是
IdCard
身份证号
String
是
Name
姓名。中文请使用 UTF-8编码
String
是
LivenessType
活体检测类型，取值：LIP/ACTION/SILENT
LIP 为数字模式，ACTION 为动作模式，SILENT 为静默模式，三种模式选择一种传入
String
是
ValidateData
数字模式传参：数字验证码（1234），需先调用接口获取数字验证码
动作模式传参：传动作顺序（2，1 or 1，2），需先调用接口获取动作顺序
静默模式传参：空
String
是。当 LivenessType 填的是 SILENT 时，该参数为可选项
BestFrameNum
需要返回多张最佳截图，取值范围1 - 10，不设置默认返回一张最佳截图
Int
否
请求头
此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。
请求体
该请求无请求体。
响应
响应头
此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。 
响应体
具体的返回内容如下：
节点名称（关键字）
父节点
描述
类型
Response
无
保存结果的容器
Container
Response 的内容：
节点名称（关键字）
父节点
描述
类型
BestFrameBase64
Response
验证通过后的视频最佳截图照片，照片为 BASE64 编码后的值，JPG 格式
注意：此字段可能返回 null，表示取不到有效值
String
Sim
Response
相似度，取值范围 [0.00, 100.00]。推荐相似度大于等于70时可判断为同一人，可根据具体场景自行调整阈值（阈值70的误通过率为千分之一，阈值80的误通过率是万分之一）
检测成功返回
Float
BestFrameList
Response
最佳截图列表，仅在配置了返回多张最佳截图时返回
注意：此字段可能返回 null，表示取不到有效值
String
实际案例
请求
GET /test.mp4?ci-process=LivenessRecognition&IdCard=11204416541220243X&Name=韦小宝&LivenessType=SILENT HTTP/1.1
Authorization: q-sign-algorithm=sha1&q-ak=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR****&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=28e9a4986df11bed0255e97ff90500557e0e****
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
响应
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 414641
Date: Thu, 15 Jun 2017 12:37:29 GMT
Server: tencent-ci
x-cos-request-id: NWY2OWFlYjdfNDQ0NjYzNjRfMTBm****
﻿
﻿
﻿
<Response>
      <BestFrameBase64>/9j/4AAQSkZJRgABAQAAAQA</BestFrameBase64>
      <Sim>100</Sim>
</Response>
错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误信息请参见 错误码 文档。
错误码
描述
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.FileSaveError
文件存储失败，请稍后重试
FailedOperation.IdFormatError
输入的身份证号有误
FailedOperation.IdNameMisMatch
姓名和身份证号不一致，请核实后重试
FailedOperation.IdNoExistSystem
库中无此号，请到户籍所在地进行核实
FailedOperation.IdPhotoNoExist
库中无此号照片，请到户籍所在地进行核实
FailedOperation.IdPhotoPoorQuality
证件图片分辨率太低，请重新上传
FailedOperation.IdPhotoSystemNoanswer
客户库自建库或认证中心返照失败，请稍后再试
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.NameFormatError
输入的姓名有误
FailedOperation.RequestLimitExceeded
调用次数超出限制
FailedOperation.SilentDetectFail
实人检测失败
FailedOperation.SilentThreshold
实人检测未达到通过标准
FailedOperation.SilentTooShort
视频录制时间过短，请录制2s以上的视频。
FailedOperation.UnKnown
内部未知错误
InvalidParameter
参数错误
InvalidParameter.RuleId
RuleId 不存在
InvalidParameterValue
参数取值错误
InvalidParameterValue.BizTokenExpired
BizToken 过期
InvalidParameterValue.RuleIdNotExist
RuleId 不存在，请到人脸核身控制台申请
UnauthorizedOperation
未授权操作
UnauthorizedOperation.Arrears
账号已欠费
UnauthorizedOperation.NonAuthorize
账号未实名
UnauthorizedOperation.Nonactivated
未开通服务
UnsupportedOperation
操作不支持
﻿

参数名称	描述	类型	是否必选
ObjectKey	对象文件名，例如：folder/document.mp4，BASE64 编码后的大小不超过8M，支持 mp4、avi、flv 格式	String	是
ci-process	数据万象处理能力，人脸核身固定为 LivenessRecognition	String	是
IdCard	身份证号	String	是
Name	姓名。中文请使用 UTF-8编码	String	是
LivenessType	活体检测类型，取值：LIP/ACTION/SILENT LIP 为数字模式，ACTION 为动作模式，SILENT 为静默模式，三种模式选择一种传入	String	是
ValidateData	数字模式传参：数字验证码（1234），需先调用接口获取数字验证码动作模式传参：传动作顺序（2，1 or 1，2），需先调用接口获取动作顺序静默模式传参：空	String	是。当 LivenessType 填的是 SILENT 时，该参数为可选项
BestFrameNum	需要返回多张最佳截图，取值范围1 - 10，不设置默认返回一张最佳截图	Int	否

节点名称（关键字）	父节点	描述	类型
Response	无	保存结果的容器	Container

错误码	描述
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.FileSaveError	文件存储失败，请稍后重试
FailedOperation.IdFormatError	输入的身份证号有误
FailedOperation.IdNameMisMatch	姓名和身份证号不一致，请核实后重试
FailedOperation.IdNoExistSystem	库中无此号，请到户籍所在地进行核实
FailedOperation.IdPhotoNoExist	库中无此号照片，请到户籍所在地进行核实
FailedOperation.IdPhotoPoorQuality	证件图片分辨率太低，请重新上传
FailedOperation.IdPhotoSystemNoanswer	客户库自建库或认证中心返照失败，请稍后再试
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.NameFormatError	输入的姓名有误
FailedOperation.RequestLimitExceeded	调用次数超出限制
FailedOperation.SilentDetectFail	实人检测失败
FailedOperation.SilentThreshold	实人检测未达到通过标准
FailedOperation.SilentTooShort	视频录制时间过短，请录制2s以上的视频。
FailedOperation.UnKnown	内部未知错误
InvalidParameter	参数错误
InvalidParameter.RuleId	RuleId 不存在
InvalidParameterValue	参数取值错误
InvalidParameterValue.BizTokenExpired	BizToken 过期
InvalidParameterValue.RuleIdNotExist	RuleId 不存在，请到人脸核身控制台申请
UnauthorizedOperation	未授权操作
UnauthorizedOperation.Arrears	账号已欠费
UnauthorizedOperation.NonAuthorize	账号未实名
UnauthorizedOperation.Nonactivated	未开通服务
UnsupportedOperation	操作不支持

活体人脸核身

本页目录：

功能描述

授权说明

服务开通

使用限制

费用说明

请求

上传时处理

云上数据处理

请求参数

请求头

请求体

响应

响应头

响应体

实际案例

请求

响应

错误码