/identity/selfie_idnumber_verification

1.接口描述

该接口在身份核验的基础上,结合用户的活体检测动作,基于模型算法的能力,优先进行图片质量检测,判断用户图片是否清晰,是否过度曝光等;再对照片进行人像定位,特征提取;并最终判断是否为用户本人。
(注:此接口只提供比对相似度分数,不提供比对照片)

  • 普通人脸图片要求
    1. 格式为 JPG(JPEG),BMP,PNG,GIF,TIFF
    2. 宽和高大于 8px,小于等于4000px
    3. 小于等于 2 MB,建议100KB以内
    4. 人脸双眼间距不小于30像素,建议90像素以上
    5. 图像中人脸图像较清晰,不因镜头散焦或运动而模糊
    6. 眼睛的瞳孔清晰可见,镜面无反光,禁止戴墨镜,且眼镜框不得遮挡眼睛,不要带宽框眼镜
    7. 人脸光线均匀且无阴影,亮度在200-800Lux,面部无明显反光、逆光、侧光
    8. 要求头发及饰物不能遮挡人脸,禁止戴口罩,帽子
    9. 表情自然、放松、无夸张动作,脸部区域完整、轮廓清晰、人脸比例不失真
    10. 照片中只允许有1张人脸,且背景简单,无复杂场景
    11. 人脸姿态要求,平面旋转(roll)±15°,俯仰变化(pitch)±10°,姿态偏转(yaw)±15°
  • 支持自动识别人脸方向
    1. 上传的图片中包含有 exif 方向信息,先按此信息旋转、翻转后再做识别人脸方向并调整。
    2. 如果照片方向混乱且 exif 方向信息不存在或不正确,自动识别人脸方向并调整

请求方式:

POST

请求URL:

https://cloudapi.linkface.cn/identity/selfie_idnumber_verification

2.请求参数

字段 类型 必需 描述
api_id string API 账户。
api_secret string API 密钥。
id_number string 身份证号。用以查询近照
name string 与身份证号相对应的姓名。身份证号及姓名相匹配才能查询近照
selfie_file file 见下方注释 需上传的图片文件。上传本地图片可选取此参数
selfie_url string 见下方注释 图片网络地址。采用抓取网络图片方式可选取此参数
selfie_image_id string 见下方注释 图片的id。在云端上传过的图片可选取此参数
selfie_image_base64 string 见下方注释 采用base64编码的二进制图片数据可选此参数
selfie_auto_rotate boolean 开启图片自动旋转功能。开通:true,不开通:false。默认不开通

参数 selfie_file,selfie_url,selfie_image_idselfie_image_base64必四选一,如同时传入多个参数,本API使用顺序为selfie_image_id优先,其次selfie_fileselfie_image_base64selfie_url

若将 URL 放入 Query String 中则需要对特殊字符进行转义,所有中文和特殊字符必需以UTF-8编码转义。 目前支持 http/https 等协议的网络地址。下载限时 5s,超时后仍未下载完成则属于失败。 参数 selfie_file 需把图片文件的内容以 multipart/form-data 的形式放到 POST 消息体中。

参数 selfie_image_base64 需要注意:图片的base64编码是不包含图片头的,如data:image/jpg;base64。

打开自动旋转功能会增加运算时间,请酌情考虑是否开通此功能

3.返回参数

字段 类型 描述
request_id string 本次请求的id。
status string 状态。正常为 OK,其他值表示失败。详见错误码
confidence float 置信度。值为 0~1,值越大表示两张照片属于同一个人的可能性越大。无法得到近照时该值为 null
identity object 接口调用结果。
selfie object 请求参数中使用file、image_base64、url方式会返回图片的id。

identity 的结构如下:

字段 类型 描述
validity boolean 身份证和姓名经过接口验证是否匹配。匹配为 true,不匹配为 false
reason string 接口出错的原因。正常为Gongan status OK 。其他错误类型参考reason字段表

reason字段详细描述:

reason字段 描述 是否收费
Gongan status OK 姓名和身份证号匹配
Gongan photo doesn’t exist 姓名和身份证号匹配,近照不存在
Name and idcard number doesn’t match 姓名与身份证号不匹配
Invalid idcard number 查无此身份证号

注:和/identity/liveness/idnumber_verification接口不同,此接口数据源返回的reason字段为Gongan photo doesn’t exist、Name and idcard number doesn’t match、Invalid idcard number返回状态码为200

>

置信度阈值与错误率对应关系:

阈值 0.4 0.5 0.6 0.7 0.8 0.9
错误率 十分之一 百分之一 千分之一 万分之一 十万分之一 百万分之一

> 备注:confidence阈值为0.7,由行业大数据训练得到,大于等于0.7是同一人

{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "OK",
  "confidence": 0.312779,
  "selfie": { 
    "image_id": "xxxxx"
  },
  "identity": {
    "validity": true,
    "photo_id": "6963927a2b1e4fbc9abd9ff15638a2b5",
    "reason": "xxx"
  }
}

4.错误码

状态码 status 字段 说明
400 PHOTO_SERVICE_ERROR 数据源服务服务出错,详情见字段 reason
400 ENCODING_ERROR 参数非UTF-8编码
400 DOWNLOAD_TIMEOUT 网络地址图片获取超时
400 DOWNLOAD_ERROR 网络地址图片获取失败
400 IMAGE_ID_NOT_EXIST 图片不存在
400 IMAGE_FILE_SIZE_TOO_BIG 图片体积过大
400 NO_FACE_DETECTED 上传的图片未检测出人脸
400 CORRUPT_IMAGE 文件不是图片文件或已经损坏
400 INVALID_IMAGE_FORMAT_OR_SIZE 图片大小或格式不符合要求
400 INVALID_ARGUMENT 请求参数错误,具体原因见 reason 字段内容
401 UNAUTHORIZED 账号或密钥错误
403 KEY_EXPIRED 账号过期,具体情况见 reason 字段内容
403 RATE_LIMIT_EXCEEDED 调用频率超出限额
403 NO_PERMISSION 无调用权限
403 OUT_OF_QUOTA 调用次数超出限额
404 NOT_FOUND 请求路径错误
500 INTERNAL_ERROR 服务器内部错误

错误情况主要分为四种情况

1.账号和服务器报错,错误码为401、403、404、500

输出报错样例:

{
  "status": "RATE_LIMIT_EXCEEDED",
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e"
}

2.输入参数报错,错误码为400,status为ENCODING_ERROR、DOWNLOAD_TIMEOUT、DOWNLOAD_ERROR、IMAGE_ID_NOT_EXIST、IMAGE_FILE_SIZE_TOO_BIG、CORRUPT_IMAGE、INVALID_IMAGE_FORMAT_OR_SIZE、INVALID_ARGUMENT ,其中根据status字段不同输出image(指哪一张图片出错)或reason

输出报错样例:

{
  "status": "DOWNLOAD_ERROR",
  "image": "selfie"
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e"
}

注:我们会对输入用户姓名和身份证进行预判,如果输入错误,status为INVALID_ARGUMENT,reason字段的描述为:Invalid name 或Invalid idcard number

3.错误码为400,status为PHOTO_SERVICE_ERROR错误时,reason字段的描述如下:

reason字段 描述 是否收费
Gongan service timeout 接口获取超时
Gongan service is unavailable temporarily 服务不可用
Network error 网络错误
Unknown error 未知错误

输出报错样例:

{
  "status": "PHOTO_SERVICE_ERROR",
  "reason": "Gongan service timeout",
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e"
}

4.如果已经调用成功数据源接口,但在接下来步骤报错(错误码为400,status为NO_FACE_DETECTED),我们会在错误响应的JSON中返回接口的状态。

字段说明如下:

identity 的结构描述:

字段 类型 描述
validity boolean 身份证和姓名经过接口验证是否匹配。匹配为 true,不匹配为 false
reason string 接口返回描述信息,正常为Gongan status OK
reason字段 描述 是否收费
poor picture quality 图片质量差

参考样例如下:

{
  "status": "NO_FACE_DETECTED",
  "image": "selfie",
  "request_id": "TIDc5721b2b7cdb488fafb1e065c4c40619",
  "identity": {
    "validity": true,
    "photo_id": "6963927a2b1e4fbc9abd9ff15638a2b5",
    "reason": "xxx"
  }
}

5.输入示例

  • cURL 样例
curl -X POST "https://cloudapi.linkface.cn/identity/selfie_idnumber_verification?api_id=ID&api_secret=SECRET" \
  -F selfie_file=@/PATH/TO/IMAGE -F id_number=NUMBER -F name=NAME
  • HTTPie 样例
http -f POST "https://cloudapi.linkface.cn/identity/selfie_idnumber_verification?api_id=ID&api_secret=SECRET" \
  selfie_file@/PATH/TO/IMAGE id_number=NUMBER name=NAME
  • C++ 样例
#include <iostream>
#include <cstring>
#include <exception>
#include <curl/curl.h>
#include <json/json.h>

using namespace std;
size_t callback(char *ptr, size_t size, size_t nmemb, string &stream){

  size_t sizes = size*nmemb;
  string temp(ptr,sizes);
  stream += temp;
  return sizes;
}
int main( int argv, char * argc[] ){

  CURL *curl;
  CURLM *multi_handle;
  CURLcode res;
  long code;
  string stream;
  struct curl_httppost *formpost = NULL;
  struct curl_httppost *lastptr = NULL;
  struct curl_slist *headerlist = NULL;

  try{

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();

    if( curl ){

      curl_formadd(&formpost,&lastptr,CURLFORM_COPYNAME,"api_id",
                  CURLFORM_COPYCONTENTS, "ID",CURLFORM_END);
      curl_formadd(&formpost,&lastptr,CURLFORM_COPYNAME,"api_secret",
                  CURLFORM_COPYCONTENTS, "SECRET",CURLFORM_END);
      curl_formadd(&formpost,&lastptr,CURLFORM_COPYNAME,"id_number",
                  CURLFORM_COPYCONTENTS, "NUMBER",CURLFORM_END);
      curl_formadd(&formpost,&lastptr,CURLFORM_COPYNAME,"name",
                  CURLFORM_COPYCONTENTS, "NAME",CURLFORM_END);
      curl_formadd(&formpost,&lastptr,CURLFORM_COPYNAME,"selfie_file",
                  CURLFORM_FILE, argc[1], CURLFORM_END);

      curl_easy_setopt(curl, CURLOPT_URL, "https://cloudapi.linkface.cn/identity/selfie_idnumber_verification");
      curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);
      curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, callback);
      curl_easy_setopt(curl, CURLOPT_WRITEDATA, &stream);

      #ifdef SKIP_PEER_VERIFICATION
        curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
      #endif
      #ifdef SKIP_HOSTNAME_VERIFICATION
        curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
      #endif

      res = curl_easy_perform(curl);

      if( res != CURLE_OK ){
        cout<<"curl_easy_perform() failed:"<<curl_easy_strerror(res)<<endl;
        return -1;
      }
      curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &code);
      Json::Value res_data;
      Json::Reader *reader = new Json::Reader(Json::Features::strictMode());
      if(!reader->parse(stream, res_data)){
        cout<<"parse error";
        return -1;
      }
      cout<<"HTTP Status Code:"<<code<<endl;
      cout<<res_data<<endl;
      curl_easy_cleanup(curl);
  }
    curl_global_cleanup();

  }catch(exception &ex){
    cout<<"curl exception:"<<ex.what()<<endl;
  }
}
  • Java 样例
import java.io.BufferedReader;
import java.io.File;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.Charset;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.FileBody;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

public class httpClientPost {
      public static final String api_id = "ID"; 
      public static final String api_secret = "SECRET";
      public static final String filepath = "C:/Users/face.jpg";//图片路径
      public static final String POST_URL = "https://cloudapi.linkface.cn/identity/selfie_idnumber_verification";
      public static final String username = "name";//姓名
      public static final String id_number = "number";//身份证号

      public static void HttpClientPost() throws ClientProtocolException, IOException {
            HttpClient httpclient = new DefaultHttpClient();
            HttpPost post = new HttpPost(POST_URL);
            StringBody id = new StringBody(api_id);
            StringBody secret = new StringBody(api_secret);
            StringBody name = new StringBody(username,Charset.forName("UTF-8"));
            StringBody number = new StringBody(id_number);
            FileBody fileBody = new FileBody(new File(filepath));
            MultipartEntity entity = new MultipartEntity();

            entity.addPart("api_id", id);
            entity.addPart("api_secret", secret);
            entity.addPart("name", name);
            entity.addPart("id_number", number);
            entity.addPart("selfie_file", fileBody);
            System.out.println(username+name);
            post.setEntity(entity);

            HttpResponse response = httpclient.execute(post);
            if (response.getStatusLine().getStatusCode() == 200) {
                HttpEntity entitys = response.getEntity();
                BufferedReader reader = new BufferedReader(
                    new InputStreamReader(entitys.getContent()));
                String line = reader.readLine();
                System.out.println(line);
            }else{
                HttpEntity r_entity = response.getEntity();
                String responseString = EntityUtils.toString(r_entity);
                System.out.println("错误码是:"+response.getStatusLine().getStatusCode()+"  "+response.getStatusLine().getReasonPhrase());
                System.out.println("出错原因是:"+responseString);
                //你需要根据出错的原因判断错误信息,并修改
            }

            httpclient.getConnectionManager().shutdown();
      }


    public static void main(String[] args) throws ClientProtocolException, IOException {
        HttpClientPost();
    }
}
  • Ruby 样例
require 'net/http/post/multipart'
require 'json'

begin
  uri = URI.parse('https://cloudapi.linkface.cn/identity/selfie_idnumber_verification')
  File.open("px.jpg") do |jpg|
    req = Net::HTTP::Post::Multipart.new uri.path,
          "selfie_file" => UploadIO.new(jpg, "image/jpeg", "px.jpg"),
          "api_id" => "ID",
          "api_secret" => "SECRET",
          "id_number" => "NUMBER",
          "name" => "NAME"
    res = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
      http.request(req)
    end
    result = JSON.parse(res.body)
    puts result
  end
rescue Exception => e
  puts e.message
end
  • Python 样例

我们提供的样例支持 Python 2.7 & 3.4–3.7 和 PyPy,其他版本暂不提供,需要您查阅相关资料。

import requests

try:
    host = 'https://cloudapi.linkface.cn'
    url = host + '/identity/selfie_idnumber_verification'
    files = {'selfie_file': open('/selfie/image/file/path', 'rb')}
    data = {'api_id': 'ID','api_secret': 'SECRET','id_number': 'ID_NUMBER','name':'NAME'}

    response = requests.post(url, files = files, data = data)
    result = response.json()
    print result
except Exception as e:
    print("type error: " + str(e))
  • PHP 样例

我们提供的样例是基于 PHP 5.5 与 PHP 5.6 两个版本,其他版本暂不提供,需要您查阅相关资料。

以下样例是基于 PHP 5.5 版本的。

<?php
   $testurl = 'https://cloudapi.linkface.cn/identity/selfie_idnumber_verification';  
   $filePath = 'C:/Users/face.jpg';  //图片路径
   $fileContent = '@' . realpath($filePath);
   $post_data = array ('api_id' => 'ID','api_secret' => 'SECRET','id_number' => 'NUMBER',
             'name' => 'NAME','selfie_file' => $fileContent);
   $ch = curl_init();
   curl_setopt($ch, CURLOPT_URL, $testurl);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);//您可以根据需要,决定是否打开SSL验证
   curl_setopt($ch, CURLOPT_POST,1);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
   $output = curl_exec($ch);
   var_dump($output);
   curl_close($ch);
?>

以下样例是基于 PHP 5.6 版本的。

<?php
   $testurl = 'https://cloudapi.linkface.cn/identity/selfie_idnumber_verification';  
   $filePath = 'C:/Users/face.jpg';  //图片路径
   $fileContent = new \CURLFile($filePath);
   $post_data = array ('api_id' => 'ID','api_secret' => 'SECRET','id_number' => 'NUMBER',
             'name' => 'NAME','selfie_file' => $fileContent);
   $ch = curl_init();
   curl_setopt($ch, CURLOPT_URL, $testurl);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);//您可以根据需要,决定是否打开SSL验证
   curl_setopt($ch, CURLOPT_POST,1);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
   $output = curl_exec($ch);
   var_dump($output);
   curl_close($ch);
?>

results matching ""

    No results matching ""