快速开始

欢迎使用识度AI人脸识别API!本文档将帮助您快速集成我们的人脸识别服务。

概述

识度AI提供高精度的人脸识别服务,包括:

  • 人脸比对:1:1人脸相似度比较
  • 人脸属性检测:检测人脸属性信息(年龄、性别、是否是活体等)
  • 人脸注册(基于人脸库):将人脸信息注册到人脸库
  • 人脸识别(基于人脸库):1:N人脸库中识别人脸
  • 人脸更新(基于人脸库):更新已注册的人脸信息
  • 人脸删除(基于人脸库):从人脸库中删除人脸信息

基础信息

API基础URL

https://facedegree.cn/api/face/v1

响应格式

所有API响应都使用JSON格式:

{
	"success": true,
	"code": "0",
	"message": "操作成功",
	"data": {
    // 具体的响应数据
  }
}

身份认证

所有API调用都需要进行身份认证。您需要在请求头中包含API密钥和密钥签名。

获取API密钥

  1. 注册并登录识度AI平台
  2. 在个人中心获取您的API密钥和密钥签名
  3. 确保您的账户有足够的API调用次数

请求头设置

在每个API请求中,您需要设置以下请求头:

api-key: your_api_key
api-secret: your_api_secret

CURL示例

// cURL示例
curl -X POST "https://facedegree.cn/api/face/v1/compareFace" \
  -H "api-key: your_api_key" \
  -H "api-secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"image1":"base64_image_1","image2":"base64_image_2"}'

API调用示例

Java 调用示例

Maven依赖

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.9.3</version>
</dependency>

JAVA示例代码

import okhttp3.*;
import java.io.IOException;

public class FaceRecognitionExample {
    private static final String API_KEY = "your_api_key";
    private static final String API_SECRET = "your_api_secret";
    private static final String BASE_URL = "https://facedegree.cn/api/face/v1";
    private static final MediaType JSON = MediaType.get("application/json; charset=utf-8");
    
    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();
        
        // 人脸比对示例
        compareFace(client);
        
        // 人脸注册示例
        registerFace(client);
    }
    
    // 人脸比对方法
    public static void compareFace(OkHttpClient client) throws IOException {
        String json = "{\\"image1\\":\\"base64_image_1\\",\\"image2\\":\\"base64_image_2\\"}";
        Request request = new Request.Builder()
                .url(BASE_URL + "/compareFace")
                .post(RequestBody.create(json, JSON))
                .addHeader("api-key", API_KEY)
                .addHeader("api-secret", API_SECRET)
                .build();
        
        try (Response response = client.newCall(request).execute()) {
            System.out.println("人脸比对结果: " + response.body().string());
        }
    }
    
    // 人脸注册方法
    public static void registerFace(OkHttpClient client) throws IOException {
        String registerJson = "{\\"faceId\\":\\"1\\",\\"faceName\\":\\"张三\\",\\"faceImg\\":\\"base64_image\\"}";
        Request registerRequest = new Request.Builder()
                .url(BASE_URL + "/registerFaceByFaceDataBase")
                .post(RequestBody.create(registerJson, JSON))
                .addHeader("api-key", API_KEY)
                .addHeader("api-secret", API_SECRET)
                .build();
        
        try (Response response = client.newCall(registerRequest).execute()) {
            System.out.println("人脸注册结果: " + response.body().string());
        }
    }
}

Python 调用示例

# 安装依赖: pip install requests

import requests
import json

class FaceRecognitionAPI:
    def __init__(self, api_key, api_secret, base_url="https://facedegree.cn/api/face/v1"):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = base_url
        self.headers = {
            'api-key': api_key,
            'api-secret': api_secret,
            'Content-Type': 'application/json'
        }
    
    def compare_face(self, image1, image2):
        url = f"{self.base_url}/compareFace"
        data = {
            'image1': image1,
            'image2': image2
        }
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()
    
    def register_face(self, face_id, face_name, face_img, check_rgb=False, check_ir=False):
        url = f"{self.base_url}/registerFaceByFaceDataBase"
        data = {
            'faceId': face_id,
            'faceName': face_name,
            'faceImg': face_img,
            'checkRGBLiveDetection': check_rgb,
            'checkIRLiveDetection': check_ir
        }
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()

# 使用示例
api = FaceRecognitionAPI('your_api_key', 'your_api_secret')

# 人脸比对
result = api.compare_face('base64_image_1', 'base64_image_2')
print(f"相似度: {result.get('data')}")

# 人脸注册
register_result = api.register_face('1', '张三', 'base64_image')
print(f"注册结果: {register_result.get('message')}")

PHP 调用示例

apiKey = $apiKey;
        $this->apiSecret = $apiSecret;
        $this->baseUrl = $baseUrl;
        $this->headers = [
            'api-key: ' . $apiKey,
            'api-secret: ' . $apiSecret,
            'Content-Type: application/json'
        ];
    }
    
    public function compareFace($image1, $image2) {
        $url = $this->baseUrl . '/compareFace';
        $data = json_encode([
            'image1' => $image1,
            'image2' => $image2
        ]);
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $this->headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    public function registerFace($faceId, $faceName, $faceImg, $checkRgb = false, $checkIr = false) {
        $url = $this->baseUrl . '/registerFaceByFaceDataBase';
        $data = json_encode([
            'faceId' => $faceId,
            'faceName' => $faceName,
            'faceImg' => $faceImg,
            'checkRGBLiveDetection' => $checkRgb,
            'checkIRLiveDetection' => $checkIr
        ]);
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $this->headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
}

// 使用示例
$api = new FaceRecognitionAPI('your_api_key', 'your_api_secret');

// 人脸比对
$result = $api->compareFace('base64_image_1', 'base64_image_2');
echo "相似度: " . ($result['data'] ?? 'N/A');

// 人脸注册
$registerResult = $api->registerFace('1', '张三', 'base64_image');
echo "注册结果: " . ($registerResult['message'] ?? 'N/A');
?>

JavaScript 调用示例

// 人脸比对
async function compareFace(image1, image2) {
    const response = await fetch('https://facedegree.cn/api/face/v1/compareFace', {
        method: 'POST',
        headers: {
            'api-key': 'your_api_key',
            'api-secret': 'your_api_secret',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            image1: image1,
            image2: image2
        })
    });
    
    const result = await response.json();
    return result;
}

// 人脸注册
async function registerFace(faceId, faceName, faceImg, checkRgb = false, checkIr = false) {
    const response = await fetch('https://facedegree.cn/api/face/v1/registerFaceByFaceDataBase', {
        method: 'POST',
        headers: {
            'api-key': 'your_api_key',
            'api-secret': 'your_api_secret',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            faceId: faceId,
            faceName: faceName,
            faceImg: faceImg,
            checkRGBLiveDetection: checkRgb,
            checkIRLiveDetection: checkIr
        })
    });
    
    const result = await response.json();
    return result;
}

// 使用示例
compareFace('base64_image_1', 'base64_image_2')
    .then(result => {
        console.log('相似度:', result.data);
    })
    .catch(error => {
        console.error('错误:', error);
    });

registerFace('1', '张三', 'base64_image')
    .then(result => {
        console.log('注册结果:', result.message);
    })
    .catch(error => {
        console.error('错误:', error);
    });

API参考

以下是所有可用API的详细说明。

人脸识别v1 API

人脸比对

比较两张人脸图片的相似度,返回相似度分数。

POST /api/face/v1/compareFace

请求格式

Content-Type: application/json

请求参数

参数名 类型 必填 说明
image1 string 第一张人脸图片的base64编码,大小不超过2MB
image2 string 第二张人脸图片的base64编码,大小不超过2MB

请求示例

{
  "image1": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
  "image2": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
}

响应示例

{
	"success": true,
	"code": "0",
	"message": "",
	"data": 0.8459455 //人脸相似度 范围0~1
}

出参说明

参数名 类型 说明
success boolean 请求是否成功
code string 业务状态码,"0"表示成功
message string 响应消息
data number 人脸相似度,范围0~1

人脸属性检测

检测人脸图片中的属性信息,如年龄、性别、表情等。

POST /api/face/v1/getFaceAttribute

请求格式

Content-Type: application/json

请求参数

参数名 类型 必填 说明
faceImg string 人脸图片的base64编码,大小不能超过2M

请求示例

{
  "faceImg": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
}

响应示例

{
	"success": true,
	"code": "0",
	"message": "",
	"data": {
		"rGBliveness": 1, //RGB活体值,未知=-1 、非活体=0 、活体=1、超出人脸=-2
		"gender": 1, //性别,未知性别=-1 、男性=0 、女性=1
		"age": 22   //年龄 0:未知; >0:年龄值
	}
}

出参说明

参数名 类型 说明
success boolean 请求是否成功
code string 业务状态码,"0"表示成功
message string 响应消息
data object 人脸属性数据对象
data.rGBliveness integer RGB活体值,未知=-1 、非活体=0 、活体=1、超出人脸=-2
data.gender integer 性别,未知性别=-1 、男性=0 、女性=1
data.age integer 年龄 0:未知; >0:年龄值

人脸注册(基于人脸库)

将人脸信息注册到人脸库中,用于后续的人脸识别。

POST /api/face/v1/registerFaceByFaceDataBase

请求格式

Content-Type: application/json

请求参数

参数名 类型 必填 说明
faceId string 人脸唯一标识符,建议传userId,长度不能超过64
faceName string 人脸名称或备注
faceImg string 人脸图片的base64编码,大小不能超过2M
checkRGBLiveDetection boolean 是否进行RGB活体检测(基于单目摄像头),默认false
checkIRLiveDetection boolean 是否进行IR活体检测(基于红外摄像头),默认false

请求示例

{
  "faceId": "1",
  "faceName": "张三",
  "faceImg": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
  "checkRGBLiveDetection": true,
  "checkIRLiveDetection": false
}

响应示例

{
	"success": true,
	"code": "0",
	"message": "",
	"data": true
}

人脸识别(基于人脸库)

在人脸库中搜索匹配的人脸,返回相似度最高的候选结果。

POST /api/face/v1/recognizeFaceByFaceDataBase

请求格式

Content-Type: application/json

请求参数

参数名 类型 必填 说明
faceImg string 待识别人脸图片的base64编码,大小不能超过2M
checkRGBLiveDetection boolean 是否进行RGB活体检测(基于单目摄像头),默认false
checkIRLiveDetection boolean 是否进行IR活体检测(基于红外摄像头),默认false

请求示例

{
  "faceImg": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
  "checkRGBLiveDetection": true,
  "checkIRLiveDetection": false
}

响应示例

{
	"success": true,
	"code": "0",
	"message": "",
	"data": [
		{
			"similar": 0.8459455,//人脸相似度,范围0~1
			"faceId": "2", //人脸唯一标识符
			"faceName": "李四" //人脸名称或备注
		}
	]
}

出参说明

参数名 类型 说明
success boolean 请求是否成功
code string 业务状态码,"0"表示成功
message string 响应消息
data array 识别结果数组
data[].similar number 人脸相似度,范围0~1
data[].faceId string 人脸唯一标识符
data[].faceName string 人脸名称或备注

人脸更新(基于人脸库)

更新已注册的人脸信息。

POST /api/face/v1/updateFaceByFaceDataBase

请求格式

Content-Type: application/json

请求参数

请求参数与人脸注册接口相同。

响应示例

{
	"success": true,
	"code": "0",
	"message": "",
	"data": true
}

人脸删除(基于人脸库)

从人脸库中删除指定的人脸信息。

GET /api/face/v1/deleteFaceByFaceDataBase

请求格式

Content-Type: application/x-www-form-urlencoded

请求参数

参数名 类型 必填 说明
faceId string 要删除的人脸ID

请求示例

GET /api/face/v1/deleteFaceByFaceDataBase?faceId=1

响应示例

{
	"success": true,
	"code": "0",
	"message": "",
	"data": true
}

错误码说明

错误响应格式

当API调用发生错误时,响应格式如下:

{
  "success": false,
  "code": "错误码",
  "message": "错误信息",
  "data": null
}

以下是所有可能返回的业务错误码及其详细说明:

错误码 错误信息 说明 解决方案
4101 IP请求频率超限 来自同一IP的请求过于频繁 降低请求频率,或等待限制时间结束
4102 api-key请求频率超限 使用同一API密钥的请求过于频繁 降低请求频率,或使用多个API密钥分散请求
4103 API密钥为空 请求头中未包含API密钥 在请求头中添加api-key参数
4104 API密钥无效或已过期 提供的API密钥不正确或已失效 检查API密钥是否正确,或重新获取有效密钥
4105 API调用次数不足 当前账户的API调用次数已用完 购买更多API调用次数或等待重新计费周期
4105 扣减API调用次数失败 扣减API调用次数时发生错误 稍后重试,如果问题持续存在请联系技术支持
5000 系统错误 服务器内部错误 稍后重试,如果问题持续存在请联系技术支持
10001 参数有误 请求参数格式不正确或缺少必需参数 检查请求参数是否符合API文档要求
11001 未检测到人脸 上传的图片中没有检测到人脸 确保图片中包含清晰的人脸,调整图片角度和光线
11002 检测到人脸数大于1 图片中检测到多张人脸 确保图片中只包含一张人脸
11003 人脸特征提取失败 无法从检测到的人脸中提取有效特征 提供更清晰的人脸图片,确保人脸角度和光线适宜
11004 人脸注册失败 人脸信息注册到人脸库失败 检查图片质量,确保人脸ID唯一性
11005 注册的人脸用户信息已存在 使用的人脸ID已经在人脸库中存在 使用不同的人脸ID,或先删除现有记录
11006 RGB活体检测失败 RGB活体检测未通过,可能是非真人 确保提供真人照片,避免使用照片或视频进行攻击
11007 IR活体检测失败 红外活体检测未通过 使用支持红外检测的设备,确保是真人操作
12001 人脸属性检测失败 无法检测人脸属性信息 确保图片中包含清晰的人脸,检查图片质量
12007 更新的人脸用户信息不存在 要更新的人脸ID在人脸库中不存在 先进行人脸注册,或检查人脸ID是否正确
12008 人脸更新失败 人脸信息更新操作失败 检查图片质量和参数有效性
12009 人脸识别失败 人脸识别过程中发生错误 检查图片质量,确保人脸库中有匹配的人脸信息
12010 人脸库中已存在相似人脸信息 人脸库中已有非常相似的人脸 检查是否重复注册,或使用不同的人脸图片
12011 删除的人脸用户信息不存在 要删除的人脸ID在人脸库中不存在 检查人脸ID是否正确
12012 人脸删除失败 从人脸库中删除人脸信息失败 确认人脸ID是否存在,检查权限设置

最佳实践

图片质量要求

  • 图片格式:支持JPEG、PNG格式
  • 图片大小:不超过2MB(10KB~50KB最优),分辨率应小于1920*1080
  • 图片分辨率:建议人脸区域至少100x100像素
  • 人脸角度:正脸效果最佳,侧脸角度不超过30度
  • 光照条件:避免强光直射和过暗环境

性能优化

  • 使用适当的图片压缩,减少传输时间,经测试单张图片识别大小为10KB~50KB时,性能及识别率最优
  • 合理控制请求频率,避免超出限制
  • 实现请求重试机制,处理网络异常
  • 缓存识别结果,避免重复请求

安全建议

  • 妥善保管API密钥,不要在客户端代码中暴露
  • 使用HTTPS协议进行API调用
  • 定期更换API密钥
  • 监控API调用日志,及时发现异常