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&timestamp&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());
    }
}