文档首页> 人证核身服务 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 ReqDataByVideoAndIdCardImage objects

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

参数

是否必选

参数类型

描述

idcard_image1

是

String

身份证人像面图像数据，使用base64编码，要求base64编码后大小不超过4M。图像各边的像素大小在300到4000之间，支持JPG格式。

idcard_image2

否

String

身份证国徽面图像数据，使用base64编码，要求base64编码后大小不超过4M。图像各边的像素大小在300到4000之间，支持JPG格式。

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 RespDataByVideoAndIdCardImage objects

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

参数

参数类型

描述

verification_result

String

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

verification_message

String

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

verification_code

Integer

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

similarity

String

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

idcard_result

IdcardResult object

身份证图像的文字识别结果，具体参见IdcardResult。

video_result

VideoResult object

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

参数

参数类型

描述

name

String

身份证上识别的名称。

number

String

身份证号。

sex

String

性别。

birth

String

出生日期。

ethnicity

String

民族。

address

String

地址。

issue

String

发证机关。

valid_from

String

有效起始日期。

valid_to

String

有效结束日期。
表11 VideoResult

参数

参数类型

描述

alive

Boolean

是否是活体。

actions

Array of ActionsList objects

动作列表。

picture

String

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

参数

参数类型

描述

confidence

Double

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

action

Integer

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

状态码： 400

表13 响应Body参数

参数

参数类型

描述

error_code

String

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

error_msg

String

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

请求示例

使用身份证正、反面图片、人脸视频进行活体人证核验

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

{
  "meta" : {
    "uuid" : "user_defined"
  },
  "data" : {
    "req_data" : [ {
      "idcard_image1" : "/9j/4AAQSkZJRgABAgEASA...",
      "idcard_image2" : "/9j/4AAAAABQSkZJRgABAg...",
      "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",
      "idcard_result" : {
        "name" : "张三",
        "sex" : "男",
        "birth" : "2000-03-06",
        "ethnicity" : "汉",
        "address" : "XX省XX市XX区XX街道XX号",
        "number" : "44***********07",
        "issue" : "XX省XX市XX区XX派出所",
        "valid_from" : "2004-08-26",
        "valid_to" : "2034-08-26"
      },
      "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

失败响应样例

错误码

错误码请参见错误码。

分享：

    相关文档

    相关产品