接口文档

H5人脸实名认证方案提供多接口能力，实现以下功能：

• 对比图片上传：上传用于1:1人脸比对的人脸底图，快速直达
• 指定用户信息上报：上传用于权威库验证时的用户身份证号码、姓名，实现无需用户拍照或手动输入，直接进行活体及识别，快速直达
• 获取认证人脸：获取认证成功最终采集的人脸信息，快速直达
• 查询认证结果：获取身份证信息（仅在使用OCR的情况下返回）、活体检测分数、人脸相似度得分，快速直达
• 实时方案视频获取：获取实时活体检测过程的视频/图片，快速直达
• 核验及计费信息获取：获取对应verify_token下的所有核验信息（人脸、身份信息、认证结果），以及后端接口（人脸实名认证V4、人脸对比V4）的计费与否及计费时间， 快读直达
  

H5人脸实名认证方案的配套功能：

• 记录查询：如您希望获取方案的记录信息，可开通记录查询功能进行可视化查看。
  
• 数据报警：通过简单设置，即可对接口的安全风险监控，为业务保驾护航。当后台监测到接口受到攻击，或其他异常情况时，将向指定的邮箱发送报警邮件，提示及时处理问题，开通数据报警功能进行可视化查看。

一、方案功能接口

1.获取verify_token接口

本接口为H5实名认证方案的verify_token获取接口，利用所获取的verify_token进行实名认证流程的有效期为2小时。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/verifyToken/generate

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求参数：

请求示例：

{
    "plan_id": 1,
    "redirect_config": {
        "success_url": "https://www.baidu.com",
        "failed_url": "https://www.baidu.com"
    },
    "access_token": "24.xxxxxxxxxxxx"
}

返回参数

• 返回结果

• 返回成功示例

  {
      "success": true,
      "result": {
          "verify_token": "Yz9rWITm4vak16PBAh5x8oG7"
      },
      "log_id": "1814798895"
  }

• 返回失败示例

  {
    "success": false,
    "result": null,
    "code": 283435,
    "message": "方案不存在。Plan not exist.",
    "log_id": "1864553256240296646"
  }
   

2.指定用户信息上报接口

本接口用于，前端在方案中选择身份信息录入-身份信息录入方式-指定用户身份核验时，需要先调用此接口输入指定用户的姓名+身份证号信息，再请求url跳转页面。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL：https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/idcard/submit

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求示例：

{
    "verify_token": "2sF3nE5mXOHkx2aQwWG4n5WI",
    "id_name": "张三",
    "id_no": "500***********3390",
    "certificate_type": 0            // 证件类型：0:大陆居民二代身份证,4:港澳台居民居住证
}

返回参数

• 返回结果

• 返回成功示例

  {
      "success": true,
      "result": 1,
      "log_id": "1244068892"
  }
    

• 返回失败示例

  {
   "success": false,
   "result": null,
   "code": 283458,
   "message": "当前链接已失效，请重试",
   "log_id": "1864553719916441372"
  }  

3.对比图片上传接口

本接口用于，在H5方案中 比对源 选择为 与上传照片比对 时，需要先调用此接口上传待比对的自建人脸库中的指定人脸图片，再请求url跳转页面。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/uploadMatchImage

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求示例：

{
    "verify_token": "2sF3nE5mXOHkx2aQwWG4n5WI",
    "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/",
    "quality_control" : "LOW",
    "liveness_control" : "LOW",
}

返回参数

• 返回结果

• 返回成功示例

  {
    "success": true,
    "result": null,
    "log_id": "1329130892"
  }

• 返回成功示例

  {
    "success": false,
    "result": null,
    "code": 283400,
    "message": "服务异常，请稍后再试",
    "log_id": "1864553950812904684"
  }

二、验证后查询接口

获取Token后，请先按照跳转实名认证H5 URL，用户进行操作后再查询接口，否则生成Token无法生效。

1.获取认证人脸接口

本接口返回进行人脸实名认证过程中进行认证的最终采集的人脸信息。根据Verify_token返回的结果信息会在云端保留3天，您可根据需要在此期间进行调取查询。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/simple

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求示例：

{
	"verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}

返回参数

• 返回结果

• 返回成功示例

{
    "success": true,
    "result": {
        "image":"https://brain.baidu.com/solution/faceprint/image/query?verify_token=xxxxxx"
    },
    "log_id": "1054986003"
}

• 返回失败示例

{
  "success": false,
  "result": null,
  "code": 283455,
  "message": "超出查询有效期。Result is expired.",
  "log_id": "1864554113296072563"
}

2.查询认证结果接口

本接口为请求返回的认证结果信息查询，包含身份证OCR识别信息、用户二次确认的身份证信息，活体检测信息、及用户对权威库图片进行比对的分数信息。（仅在认证成功时返回上述信息，认证失败返回错误码）根据Verify_token返回的结果信息会在云端保留3天，您可根据需要在此期间进行调取查询。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/detail

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求示例：

{
	"verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}

返回参数

• 返回结果

• 返回示例

  {
    "success": true,
    "result": {
        "verify_result": {
            "score": 93.7835,
            "liveness_score": 0.9672966,
            "spoofing": 0.0
        },
        "idcard_ocr_result": {
            "birthday": "19960216",
            "issue_authority": "胶南市公安局",
            "address": "山东省***********",
            "gender": "女",
            "nation": "汉",
            "expire_time": "20221103",
            "name": "柴*",
            "issue_time": "20121103",
            "id_card_number": "370***********5826"
        },
        "idcard_images": {
            "front_base64": "/9j/4AAQSkZJRgAB....",
            "back_base64": "/9j/4AAQSkZJRgAB...."
     },
        "idcard_confirm": {
            "idcard_number": "370***********5826",
            "name": "柴*"
        }
    },
    "log_id": "160931948204246"
  }

• 返回失败示例

  {
   "success": false,
   "result": null,
   "code": 283437,
   "message": "Token无效或已过期，请重新生成",
   "log_id": "1864555045677258973"
  }

3.查询统计结果

根据Verify_token返回的结果信息会在云端保留3天，您可根据需要在此期间进行调取查询。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/stat

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求示例：

{
	"verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}

返回参数

• 返回结果

• 返回示例

  {
      "success": true,
      "result": {
          "Verify_FIN": [
              {
                  "error_code": 0,
                  "count": 1
              }
          ],
           "Sessioncode": [
              {
                  "error_code": 0,
                  "count": 1
              }
          ],
          "OCR": [
              {
                  "error_code": 0,
                  "count": 2
              }
          ],
          "verify": [
              {
                  "error_code": 0,
                  "count": 1
              }
          ],
          "VideoLiveness": [
              {
                  "error_code": 0,
                  "count": 1
              }
          ]
          "Livenesscolorful": [
              {
                  "error_code": 0,
                  "count": 1
              }
          ]
          "VerifySec": [
              {
                  "error_code": 0,
                  "count": 1
              }
          ]
      },
      "log_id": "1405335905"
  }

• 返回失败示例

{
  "success": false,
  "result": null,
  "code": 283437,
  "message": "Token无效或已过期，请重新生成",
  "log_id": "1864555045677258973"
}

4.实时方案视频获取

根据Verify_token返回的视频url会在云端保留1天，您可根据需要在此期间进行调取查询。

注意：H5方案中的视频录制功能默认不开启，调用本接口将无法获得视频数据，如您需要使用以上api，请联系商务经理或提交工单申请配置开通

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/media/query

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求示例：

{
	"verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}

返回参数

• 返回结果

• 返回示例

  {
    "success": true,
    "result": {
        "processVideo": [
            "http://bj.bcebos.com/v1/aa.mp4"
        ],
        "video": [
            "http://bj.bcebos.com/v1/aa.mp4"
        ],
        "images": [
            "http://bj.bcebos.com/v1/aa.jpg"
        ],
        "extInfo": null
    },
    "log_id": "1534116864874049322"
}

• 返回失败示例

  {
   "success": false,
   "result": null,
   "code": 283437,
   "message": "Token无效或已过期，请重新生成",
   "log_id": "1864555045677258973"
  }

5.核验及计费信息获取

根据Verify_token返回的信息会在云端保留3天，您可根据需要在此期间进行调取查询。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/getall

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求示例：

{
	"verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}

返回参数

• 返回结果

• 返回示例

{
    "success":true,
    "log_id":"123456",
    "result":{
        "verify_count":1,
        "ocr_charge_count":1,
        "match_charge_count":1,
        "verify_charge_count":1,
        "verify_result":[
            {
                "order":1,
                "is_verify_passed":true,
                "code":"0",
                "message":"",
                "verify_time":"2023-10-10 10:10:10",
                "is_charged":true,
                "charge_type":"verify",
                "charge_time":"2023-10-10 10:10:10",
                "is_ocr_charge":true,
                "ocr_count":2,
                "ocr_charge_time":"2023-10-10 10:10:10",
                "verify_detail":{
                    "face_image":"xxx.jpg",
                    "verify_log_id":"xxx",
                    "score":89.9,
                    "threshold":80,
                    "liveness_score":80,
                    "spoofing_score":80,
                    "risk_level":"1",
                    "risk_tag":"xxx",
                    "is_demote":false
                },
                "idcard_confirm":{
                    "name":"张三",
                    "idcard_number":"36213219923232X",
                    "idcard_type":"0",
                    "idcard_ocr_result":{
                        "address":"江西省赣州市",
                        "birthday":"2020-10-10 10:10:10",
                        "name":"张三",
                        "idcard_number":"36213219923232X",
                        "idcard_type":"0",
                        "gender":"男",
                        "nation":"汉族",
                        "issue_time":"2020-10-10 10:10:10",
                        "expire_time":"2028-10-10 10:10:10",
                        "issue_authority":"江西省赣州市"
                    },
                    "idcard_images":{
                        "front_image":"xxx.jpg",
                        "back_image":"xxx.jpg"
                    }
                }
            }
        ]
    }
}

• 返回失败示例

  {
   "success": false,
   "result": null,
   "code": 283437,
   "message": "Token无效或已过期，请重新生成",
   "log_id": "1864555045677258973"
  }

三、常见问题

1. verify_token的详细说明

（1）access_token 有效期为 30 天，重复生成 access_token 的话，对之前的不影响，依旧能使用；access_token 与verify_token 是包含关系，即 verify_token 是由 access_token生成的，如果一个 verify_token 是和一个不匹配的 access_token 使用，会提示“Token无效或者已过期”

（2）verify_token 的核验有效期为 2 小时，在有效期内可以进行了核验动作，如果超过了 2 小时没有使用该 token 进行核验的话会提示“Token无效或者已过期”

（3） verify_token 核验完毕后（核验成功，或设置了认证未通过时URL失效），无法再进行核验，如果再次进行核验，会提示“Token无效或者已过期”

（4） verify_token 核验完毕后（核验成功，或设置了认证未通过时URL失效），支持对后验接口的查询，有效期均为 3 天，3 天后再次查询后验接口，会提示“Token无效或者已过期”

2. 获取认证人脸、查询认证结果、核验及计费信息获取接口持续返回错误码18，提示openapi限制，且有返回logid

答：检查H5方案依赖的“人脸实名认证V4”、“人脸对比V4”两项付费接口，是否有免费额度，或者直接开通后付费，以消除该报错提示。开通后，再进行重试。