控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

活体人脸核身

最近更新时间:2021-07-23 10:00:15

功能描述

集成了活体检测和跟权威库进行比对的能力,传入一段视频和姓名、身份证号信息即可进行验证。对录制的自拍视频进行活体检测,从而确认当前用户为真人,可防止照片、视频、静态3D 建模等各种不同类型的攻击。检测为真人后,再判断该视频中的人与权威库的证件照是否属于同一个人,实现用户身份信息核实。

说明:

  • 当前活体人脸核身的视频片限制为:用于活体检测的视频 BASE64 编码后的大小不超过8M,支持 mp4、avi、flv 格式。
  • 活体人脸核身为付费服务,由数据万象收取,计费详情请参见 内容审核费用
  • 该功能目前仅提供 API 使用方式。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

请求

上传时处理

视频上传时检测的请求包与对象存储(Cloud Object Storage,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-image
    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 操作不支持
    目录