/hackness/liveness_hack_detect
1.接口描述
该API功能为检测用户拍摄的活体数据是否活人。
注1：此接口只能配合Android活体检测SDK或者iOS活体检测SDK使用；
注2：protobuf文件中包含加密的人脸图片、视频等活体数据，与移动端SDK设置参数OUTPUT_TYPE有关；
注3：文档中描述的“protobuf文件”、“加密文件”、“二进制文件”均为同一个意思。
请求方式
POST
请求 URL
https://cloudapi.linkface.cn/hackness/liveness_hack_detect
2.请求参数
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| api_id | string | 是 | API 账户 |
| api_secret | string | 是 | API 密钥 |
| liveness_data_file | file | 见下方注释 | 活体检测SDK返回的protobuf文件，上传本地文件进行检测时选取此参数 |
| liveness_data_url | string | 见下方注释 | 活体检测SDK返回的protobuf文件的url，采用抓取网络文件方式时需选取此参数 |
| liveness_data_id | string | 见下方注释 | 活体检测SDK返回的protobuf文件的id，在云端上传过文件可采用此参数 |
请求参数
liveness_data_file,liveness_data_url与liveness_data_id三选一。url 中含有不少特殊字符，若将 URL 放入 Query String 中则需要对这些字符进行转义，所有中文和特殊字符必需以UTF-8编码转义。 目前支持 http/https 等协议的网络地址。下载限时 5s，超时后仍未下载完成则属于失败。
> 备注：hack_score阈值为0.98，由行业大数据训练得到，大于0.98是hack行为，小于等于0.98是正常活人
3.返回参数
正常响应
| 字段 | 类型 | 说明 |
|---|---|---|
| request_id | string | 本次请求的id |
| status | string | 状态，正常为 OK，其他值表示失败，详见错误码 |
| score | float | 分数。取值范围是0~1。值越大，表示被hack的可能性越大 |
| liveness_data_id | string | 使用file、url方式上传protobuff文件返回的云端protobuff文件的id |
返回样例
{
"request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
"status": "OK",
"score": "xxxxxx",
"liveness_data_id": "xxxxxx"
}
4.错误码
| 状态码 | status 字段 |
说明 |
|---|---|---|
400 |
ENCODING_ERROR | 参数非UTF-8编码 |
400 |
DOWNLOAD_TIMEOUT | 网络地址图片获取超时 |
400 |
DOWNLOAD_ERROR | 网络地址图片获取失败 |
400 |
INVALID_ARGUMENT | 请求参数错误，具体原因见 reason 字段内容 |
400 |
WRONG_LIVENESS_DATA | liveness_data 出错 |
400 |
NO_FACE_DETECTED | 图片未检测出人脸 ，详情见字段 image |
401 |
UNAUTHORIZED | 账号或密钥错误 |
401 |
KEY_EXPIRED | 账号过期，具体情况见 reason 字段内容 |
403 |
RATE_LIMIT_EXCEEDED | 调用频率超出限额 |
403 |
NO_PERMISSION | 无调用权限 |
403 |
OUT_OF_QUOTA | 调用次数超出限额 |
404 |
NOT_FOUND | 请求路径错误 |
500 |
INTERNAL_ERROR | 服务器内部错误 |
返回样例
{
"status": "INVALID_ARGUMENT",
"reason": "must specify 'liveness_data_file', 'liveness_data_url' or 'liveness_data_id' argument",
"request_id": "TIDa892b593c0354b0e989b5db67a331607"
}
5.输入示例
cURL样例
curl -X POST "https://cloudapi.linkface.cn/hackness/liveness_hack_detect?api_id=ID&api_secret=SECRET" \
-F file=@/PATH/TO/IMAGE
HTTPie 样例
http -f POST "https://cloudapi.linkface.cn/hackness/liveness_hack_detect?api_id=ID&api_secret=SECRET" \
file@/PATH/TO/IMAGE
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,"file",
CURLFORM_FILE, argc[1], CURLFORM_END);
curl_easy_setopt(curl, CURLOPT_URL, "https://cloudapi.linkface.cn/hackness/liveness_hack_detect");
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 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/card.jpg";//图片路径
public static final String POST_URL = "https://cloudapi.linkface.cn/hackness/liveness_hack_detect";
public static void HttpClientPost() throws ClientProtocolException, IOException {
HttpClient httpclient = new DefaultHttpClient();
HttpPost post = new HttpPost(POST_URL);
FileBody fileBody = new FileBody(new File(filepath));
StringBody id = new StringBody(api_id);
StringBody secret = new StringBody(api_secret);
MultipartEntity entity = new MultipartEntity();
entity.addPart("file", fileBody);
entity.addPart("api_id", id);
entity.addPart("api_secret", secret);
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/hackness/liveness_hack_detect')
File.open("px.jpg") do |jpg|
req = Net::HTTP::Post::Multipart.new uri.path,
"file" => UploadIO.new(jpg, "image/jpeg", "bankcard.jpg"),
"api_id" => "ID",
"api_secret" => "SECRET"
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 + '/hackness/liveness_hack_detect'
files = {'file': open('/image/file/path', 'rb')}
data = {'api_id': 'ID','api_secret': 'SECRET'}
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/hackness/liveness_hack_detect';
$filePath = 'C:/Users/face.jpg'; //图片路径
$fileContent = '@' . realpath($filePath);
$post_data = array ('api_id' => 'ID','api_secret' => 'SECRET',
'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/hackness/liveness_hack_detect';
$filePath = 'C:/Users/face.jpg'; //图片路径
$fileContent = new \CURLFile($filePath);
$post_data = array ('api_id' => 'ID','api_secret' => 'SECRET',
'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);
?>
以下样例是基于 OC 版本的。
NSString *baseUrlString = @"https://cloudapi.linkface.cn/";
NSString *urlString = @"identity/liveness_idnumber_verification";
NSDictionary *parameters = @{@"api_id": @"your_api_id", @"api_secret": @"your_api_secret"};
AFHTTPRequestOperationManager *requestOperationManager = [[MDFRequestManager sharedInstance] requestManagerForBaseURL:baseUrlString certificates:nil];
requestOperationManager.requestSerializer.timeoutInterval = requestOperationManager.reachabilityManager.reachableViaWiFi ? 30 : 45;
requestOperationManager.requestSerializer = [AFHTTPRequestSerializer serializer];
requestOperationManager.responseSerializer = [AFJSONResponseSerializer serializer];
void (^successBlock)(AFHTTPRequestOperation *operation, id responseObject) = ^(AFHTTPRequestOperation *operation, id responseObject) {
NSLog(@"responseObject:%@",responseObject);
};
void (^failBlock)(AFHTTPRequestOperation *operation, NSError *error) = ^(AFHTTPRequestOperation *operation, NSError *error){
NSLog(@"error:%@",error);
};
[requestOperationManager POST:urlString parameters:parameters constructingBodyWithBlock:^(id<AFMultipartFormData> formData) {
[formData appendPartWithFileData:encryTarData name:@"liveness_data_file" fileName:@"liveness_data_file" mimeType:@"image/jpeg"];
} success:successBlock failure:failBlock];
[formData appendPartWithFileData:self.encryTarData name:@"liveness_data_file" fileName:@"chunk" mimeType:@"image/jpeg"];