/identity/selfie_idnumber_verification
1.接口描述
该接口在身份核验的基础上,结合用户的活体检测动作,基于模型算法的能力,优先进行图片质量检测,判断用户图片是否清晰,是否过度曝光等;再对照片进行人像定位,特征提取;并最终判断是否为用户本人。
(注:此接口只提供比对相似度分数,不提供比对照片)
- 普通人脸图片要求
- 格式为 JPG(JPEG),BMP,PNG,GIF,TIFF
- 宽和高大于 8px,小于等于4000px
- 小于等于 2 MB,建议100KB以内
- 人脸双眼间距不小于30像素,建议90像素以上
- 图像中人脸图像较清晰,不因镜头散焦或运动而模糊
- 眼睛的瞳孔清晰可见,镜面无反光,禁止戴墨镜,且眼镜框不得遮挡眼睛,不要带宽框眼镜
- 人脸光线均匀且无阴影,亮度在200-800Lux,面部无明显反光、逆光、侧光
- 要求头发及饰物不能遮挡人脸,禁止戴口罩,帽子
- 表情自然、放松、无夸张动作,脸部区域完整、轮廓清晰、人脸比例不失真
- 照片中只允许有1张人脸,且背景简单,无复杂场景
- 人脸姿态要求,平面旋转(roll)±15°,俯仰变化(pitch)±10°,姿态偏转(yaw)±15°
- 支持自动识别人脸方向
- 上传的图片中包含有 exif 方向信息,先按此信息旋转、翻转后再做识别人脸方向并调整。
- 如果照片方向混乱且 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_id
与selfie_image_base64
必四选一,如同时传入多个参数,本API使用顺序为selfie_image_id
优先,其次selfie_file
、selfie_image_base64
、selfie_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);
?>