快速开始
欢迎使用识度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密钥
- 注册并登录识度AI平台
- 在个人中心获取您的API密钥和密钥签名
- 确保您的账户有足够的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调用日志,及时发现异常