1.接口说明
人脸活体检测接口用于判断上传的人脸是否为真实活体,能够识别常见攻击方式(翻拍、视频、面具等),并返回活体分数与风险信息,可与人脸比对组合完成实名核身与风控。
1.1 主要功能
- 精准活体:
- 支持复杂光照、姿态,识别多种攻击载体。
- 快速响应:
- 云端计算,接口延迟低,适合实时业务。
- 简单接入:
- 提供多语言示例与双认证方式,快速上线。
1.2 典型场景
实名认证、线上开户、刷脸登录、防舞弊、远程监考、线上贷前风控等。
2.请求信息
2.1 请求地址(URL)
POST http(s)://face-api.shiliuai.com/api/face_liveness/v1
2.2 请求方式
POST
2.3 请求头(header)
| 参数 | 类型 | 说明 |
|---|---|---|
| Content-Type | string | application/json |
| Authorization | string | 'APPCODE ' + 您的AppCode (注意英文空格) |
| 参数 | 类型 | 说明 |
|---|---|---|
| Content-Type | string | application/json |
| x-ca-key | string | 您的AppKey |
| x-ca-timestamp | string | 时间戳(毫秒) |
| x-ca-signature | string | 签名sign,md5(app_key×tamp&app_secret) |
2.4 请求体(body)
| 参数 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| image_base64 | 是 | string | 人脸图片Base64,像素[15,8192],小于20M |
| thresh | 否 | float | 活体阈值,默认0.8,分数大于阈值判为活体 |
3.返回信息
3.1 返回类型
JSON
3.2 返回码
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | int | 200表示成功 |
| message | string | 返回信息 |
3.3 返回字段
| 参数 | 类型 | 说明 |
|---|---|---|
| code | int | 错误码 |
| msg | string | 错误信息(英文) |
| msg_cn | string | 错误信息(中文) |
| success | bool | 请求是否成功 |
| request_id | string | 唯一请求ID |
| data | object | 活体检测结果 |
3.3.1 data 信息
| 参数 | 类型 | 说明 | 示例 |
|---|---|---|---|
| liveness_score | float | 活体分数[0,1] | 0.93 |
| is_live | bool | 是否判定为活体(分数>阈值) | true |
| risk_reason | string | 风险原因或为空 | "" |
3.4 返回示例
{
"code": 200,
"msg": "ok",
"msg_cn": "成功",
"success": true,
"request_id": "c3f2b18e77",
"data": {
"liveness_score": 0.937,
"is_live": true,
"risk_reason": ""
}
}
3.5 错误码
| 错误码 | 含义 |
|---|---|
| 4001 | 图片为空或格式错误 |
| 4002 | 未检测到人脸 |
| 4004 | 疑似翻拍或攻击,未通过活体 |
| 5000 | 服务内部错误,请稍后重试 |
4.示例代码
4.1 Python
import base64, json, requests
def get_b64(path):
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode()
url = "https://face-api.shiliuai.com/api/face_liveness/v1"
headers = {
"Authorization": "APPCODE 你的APPCODE",
"Content-Type": "application/json"
}
body = {"image_base64": get_b64("face_live.jpg")}
print(requests.post(url, headers=headers, data=json.dumps(body), timeout=10).text)
import base64, json, requests, hashlib, time
def get_b64(path):
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode()
def md5(s): return hashlib.md5(s.encode()).hexdigest()
url = "https://face-api.shiliuai.com/api/face_liveness/v1"
app_key = "你的APPKEY"
app_secret = "你的APPSECRET"
ts = str(int(time.time()*1000))
sign = md5(f"{app_key}&{ts}&{app_secret}")
headers = {
"x-ca-key": app_key,
"x-ca-timestamp": ts,
"x-ca-signature": sign,
"Content-Type": "application/json"
}
body = {"image_base64": get_b64("face_live.jpg")}
print(requests.post(url, headers=headers, data=json.dumps(body), timeout=10).text)
4.2 PHP
get_base64("face_live.jpg")];
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_SSL_VERIFYPEER => false
]);
echo curl_exec($ch);
?>
get_base64("face_live.jpg")];
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_SSL_VERIFYPEER => false
]);
echo curl_exec($ch);
?>
4.3 Java
import com.alibaba.fastjson2.JSONObject;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.HttpResponse;
import org.apache.http.util.EntityUtils;
import org.apache.commons.io.FileUtils;
import java.io.File;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;
public class FaceLiveEasy {
static String getBase64(String path) throws Exception {
return Base64.getEncoder().encodeToString(FileUtils.readFileToByteArray(new File(path)));
}
public static void main(String[] args) throws Exception {
String url = "https://face-api.shiliuai.com/api/face_liveness/v1";
Map headers = new HashMap<>();
headers.put("Authorization","APPCODE 你的APPCODE");
headers.put("Content-Type","application/json");
JSONObject req = new JSONObject();
req.put("image_base64", getBase64("face_live.jpg"));
try(CloseableHttpClient client = HttpClients.createDefault()) {
HttpPost post = new HttpPost(url);
headers.forEach(post::addHeader);
post.setEntity(new StringEntity(req.toJSONString(),"UTF-8"));
HttpResponse resp = client.execute(post);
System.out.println(EntityUtils.toString(resp.getEntity(),"UTF-8"));
}
}
}
import com.alibaba.fastjson2.JSONObject;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.HttpResponse;
import org.apache.http.util.EntityUtils;
import org.apache.commons.io.FileUtils;
import java.io.File;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;
import java.security.MessageDigest;
public class FaceLiveSign {
static String getBase64(String path) throws Exception {
return Base64.getEncoder().encodeToString(FileUtils.readFileToByteArray(new File(path)));
}
static String md5(String s) throws Exception {
MessageDigest md = MessageDigest.getInstance("MD5");
byte[] d = md.digest(s.getBytes("UTF-8"));
StringBuilder sb = new StringBuilder();
for(byte b:d) sb.append(String.format("%02x", b));
return sb.toString();
}
public static void main(String[] args) throws Exception {
String url = "https://face-api.shiliuai.com/api/face_liveness/v1";
String appKey = "你的APPKEY";
String appSecret = "你的APPSECRET";
String ts = String.valueOf(System.currentTimeMillis());
String sign = md5(appKey + "&" + ts + "&" + appSecret);
Map headers = new HashMap<>();
headers.put("x-ca-key", appKey);
headers.put("x-ca-timestamp", ts);
headers.put("x-ca-signature", sign);
headers.put("Content-Type","application/json");
JSONObject req = new JSONObject();
req.put("image_base64", getBase64("face_live.jpg"));
try(CloseableHttpClient client = HttpClients.createDefault()) {
HttpPost post = new HttpPost(url);
headers.forEach(post::addHeader);
post.setEntity(new StringEntity(req.toJSONString(),"UTF-8"));
HttpResponse resp = client.execute(post);
System.out.println(EntityUtils.toString(resp.getEntity(),"UTF-8"));
}
}
}
4.4 C#
using System;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json.Linq;
using System.IO;
class FaceLiveEasy {
static string GetBase64(string path) => Convert.ToBase64String(File.ReadAllBytes(path));
static async System.Threading.Tasks.Task Main() {
var url = "https://face-api.shiliuai.com/api/face_liveness/v1";
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization","APPCODE 你的APPCODE");
var body = new JObject { ["image_base64"] = GetBase64("face_live.jpg") }.ToString();
var resp = await client.PostAsync(url, new StringContent(body, Encoding.UTF8, "application/json"));
Console.WriteLine(await resp.Content.ReadAsStringAsync());
}
}
using System;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json.Linq;
using System.IO;
using System.Security.Cryptography;
class FaceLiveSign {
static string GetBase64(string path) => Convert.ToBase64String(File.ReadAllBytes(path));
static string Md5(string s){
using var md5 = MD5.Create();
var bytes = md5.ComputeHash(Encoding.UTF8.GetBytes(s));
var sb = new StringBuilder();
foreach(var b in bytes) sb.Append(b.ToString("x2"));
return sb.ToString();
}
static async System.Threading.Tasks.Task Main() {
var url = "https://face-api.shiliuai.com/api/face_liveness/v1";
var appKey = "你的APPKEY";
var appSecret = "你的APPSECRET";
var ts = DateTimeOffset.Now.ToUnixTimeMilliseconds().ToString();
var sign = Md5($"{appKey}&{ts}&{appSecret}");
var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-ca-key", appKey);
client.DefaultRequestHeaders.Add("x-ca-timestamp", ts);
client.DefaultRequestHeaders.Add("x-ca-signature", sign);
var body = new JObject { ["image_base64"] = GetBase64("face_live.jpg") }.ToString();
var resp = await client.PostAsync(url, new StringContent(body, Encoding.UTF8, "application/json"));
Console.WriteLine(await resp.Content.ReadAsStringAsync());
}
}