文档首页/ 人证核身服务 IVS/ API参考/ API/ 标准版（三要素）/ 使用身份证文本、人脸视频验证
更新时间：2024-04-29 GMT+08:00
查看PDF
分享

使用身份证文本、人脸视频验证

功能介绍

使用姓名、身份证号文本，并对视频做活体检测后提取人脸图片，以此进行三要素身份审核。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

URI

POST /v2.0/ivs-standard

请求参数

表1 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

X-Auth-Token值获取方法请参见认证鉴权。

Enterprise-Project-Id

否

String

企业项目ID。IVS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账。

获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。

企业项目创建步骤请参见用户指南。

说明：

说明： 创建企业项目后，在传参时，有以下三类场景。

  • 携带正确的ID，正常使用IVS服务，账单的企业项目会被分类到企业ID对应的企业项目中。
  • 携带格式正确但不存在的ID，正常使用IVS服务，账单的企业项目会显示对应不存在的企业项目ID。
  • 不携带ID或格式错误ID（包含特殊字符等），正常使用IVS服务，账单的企业项目会被分类到"default"中。
表2 请求Body参数

参数

是否必选

参数类型

描述

meta

是

Meta object

请求元数据，例如表征本次请求的唯一标注uuid。

data

是

data object

请求消息的数据部分。
表3 Meta

参数

是否必选

参数类型

描述

uuid

否

String

唯一标识此次请求的ID，用户自定义，不超过64位。
表4 data

参数

是否必选

参数类型

描述

req_data

否

Array of StandardReqDataByVideoAndNameAndId objects

请求列表，用于支持批量调用。目前暂时只支持单个数据查询。
表5 StandardReqDataByVideoAndNameAndId

参数

是否必选

参数类型

描述

verification_name

是

String

被验证人的姓名。

verification_id

是

String

被验证人的身份证号码。

video

是

String

现场拍摄人像视频数据，使用base64编码。

  • 视频文件大小不超过8MB，建议客户端压缩到200KB~2MB。要求base64编码后大小不超过10M。
  • 限制视频时长1～15秒。
  • 建议帧率10fps～30fps。
  • 封装格式：mp4、avi、flv、webm、asf、mov。
  • 视频编码格式：h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。

actions

是

String

动作代码顺序列表，英文逗号（,）分隔。建议单动作，目前支持的动作有： 1：左摇头 2：右摇头 3：点头 4：嘴部动作

嘴部动作建议嘴唇距离大于3厘米，左右摇头动作建议角度15-30度。

nod_threshold

否

Double

该参数为点头动作幅度的判断门限，取值范围：[1,90]，默认为10，单位为度。该值设置越大，则越难判断为点头。

detail

否

Boolean

响应参数similarity是否详细显示,默认为false。

  • true表示响应中的similarity为0~1000的小数。
  • false表示响应中的similarity为0~100的整数。

响应参数

状态码： 200

表6 响应Body参数

参数

参数类型

描述

meta

Meta object

请求元数据，例如表征本次请求的唯一标注uuid。

result

result object

调用返回结果。
表7 Meta

参数

参数类型

描述

uuid

String

唯一标识此次请求的ID，用户自定义，不超过64位。
表8 result

参数

参数类型

描述

service_name

String

子服务名称。

count

Integer

执行检测的数量，与resp_data字段对应。

resp_data

Array of StandardRespDataByVideoAndNameAndId objects

请求列表，用于支持批量调用。目前暂时只支持单个数据查询。
表9 StandardRespDataByVideoAndNameAndId

参数

参数类型

描述

verification_result

String

审核校验结果： "valid"表示身份审核通过； "invalid"表示身份审核不通过； "nonexistent"表示数据源没有该身份证号码，这种情况一般是被验证人正在办理户籍迁移，或者被验证人是军人或政要。

verification_message

String

审核校验信息，具体参考校验信息说明

verification_code

Integer

审核校验代码，具体参考校验信息说明

similarity

String

人像相识度。取值范围[0,100]，当入参detail为true时，取值范围为[0,1000]。

video_result

VideoResult object

动作活体检测的检测结果。
表10 VideoResult

参数

参数类型

描述

alive

Boolean

是否是活体。

actions

Array of ActionsList objects

动作列表。

picture

String

检测出最大人脸的图片base64。
表11 ActionsList

参数

参数类型

描述

confidence

Double

置信度，取值范围0～1。

action

Integer

动作编号，取值范围：[1,2,3,4]，其中： 1：左摇头 2：右摇头 3：点头 4：嘴部动作

状态码： 400

表12 响应Body参数

参数

参数类型

描述

error_code

String

调用失败时的错误码，具体请参考错误码。 调用成功时无此字段。

error_msg

String

调用失败时的错误信息。 调用成功时无此字段。

请求示例

使用身份证姓名、号码、人脸视频进行活体人证核验

POST https://{endpoint}/v2.0/ivs-standard

{
  "meta" : {
    "uuid" : "user_defined"
  },
  "data" : {
    "req_data" : [ {
      "verification_name" : "张三",
      "verification_id" : "44***********07",
      "video" : "/9j/4AAQSkZJRgABAgEASABIAAD...",
      "actions" : "1,3,2",
      "nod_threshold" : 10
    } ]
  }
}

响应示例

状态码： 200

OK

{
  "meta" : {
    "uuid" : "user_defined"
  },
  "result" : {
    "service_name" : "ivs-standard",
    "count" : 1,
    "resp_data" : [ {
      "verification_result" : "valid",
      "verification_message" : "Successful certification",
      "verification_code" : 1000,
      "similarity" : "65",
      "video_result" : {
        "alive" : true,
        "actions" : [ {
          "confidence" : 0.823,
          "action" : 1
        }, {
          "confidence" : 0.823,
          "action" : 3
        }, {
          "confidence" : 0.823,
          "action" : 2
        } ],
        "picture" : "/9j/4AAQSkZJRgABAQEAYABgAAD/2w..."
      }
    } ]
  }
}

状态码： 400

失败响应样例

{
  "error_code" : "IVS.0003",
  "error_msg" : "Some necessary request parameters in req_data is null."
}

状态码

状态码

描述

200

OK

400

失败响应样例

错误码

错误码请参见错误码。

相关文档