人脸识别

从您托管在我们这里的人脸库中认出照片里的人：先以姓名登记人脸，之后即可在后续图像中识别，一次识别一张脸或全部人脸。

POST/v3/store/ekyc/face-recognition/single

另有 7 个端点

试一试

• 价格0.3 IC每次请求
• 累计调用44.1K次

• v1.3.0
• 运行中

输入

file

photo.jpg

company

iApp

输出POST /v3/store/ekyc/face-recognition/single

message

successfully performed

company

YOUR_COMPANY

name

John Doe

recognition_score

0.8523

detection_score

0.9998

bbox

xmin: 154.39 ymin: 155.49 xmax: 255.45 ymax: 282.88

process_time

0.4776

全部字段见“响应”一节其他端点：/add, /check, /export, /facecrop, /import, /multi, /remove 见请求

请求

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/single \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "company=iApp"

响应

200成功。字段在"响应"一节说明。

{
  "message": "successfully performed",
  "company": "YOUR_COMPANY",
  "name": "John Doe",
  "recognition_score": 0.8523,
  "detection_score": 0.9998,
  "bbox": {
    "xmin": 154.39,
    "ymin": 155.49,
    "xmax": 255.45,
    "ymax": 282.88
  },
  "process_time": 0.4776
}

请求

multipart/form-data。每次调用都以 company 指定人脸库，修改人脸库的调用还需提供其 password；演示库为 iApp，密码 iApp。

请求头

apikeystring必填

您的 API 密钥，在控制台的 API Keys 中创建。

请求体

filefile必填

照片。JPEG 或 PNG，最大 2 MB，至少 600 × 400 像素；人脸至少 112 × 112 像素。

companystring必填

您的公司标识，即人脸库的名称。

端点	作用	价格
/v3/store/ekyc/face-recognition/single	识别最显著的一张脸	每次请求 0.3 IC
/v3/store/ekyc/face-recognition/multi	识别全部人脸，位于 faces[]	每次请求 0.3 IC
/v3/store/ekyc/face-recognition/add	以 name 登记一张脸	每次请求 0.1 IC
/v3/store/ekyc/face-recognition/remove	删除一个 name，或某个 face_id	免费
/v3/store/ekyc/face-recognition/check	统计人脸库；save_file=1 以 CSV 返回	每次请求 0.3 IC
/v3/store/ekyc/face-recognition/import、/export	以 CSV 或 Excel（type_file）导入、导出人脸特征	免费

人脸库调用

端点	字段	返回
/add	file、company、name、password	face_id、detection_score
/remove	company、name、password，多条记录时以 face_id 指定一条	removed_count
/check	company、password、save_file	total_faces、total_persons、database_size、last_updated
/import	file（含 name、face_id、feature_vector 的 CSV）、company、password	imported_count、failed_count
/export	company、password、type_file = csv 或 excel	文件

每人登记 3 至 5 张清晰、正面、光线充足且表情略有变化的照片。服务使用的阈值为 detection 0.75、comparison 0.80、recognition 0.85。演示库不支持导入和导出。

响应

/single 在顶层返回最佳匹配，如右侧面板所示；/multi 在 faces 中为每张脸返回相同字段。

namestring

登记的姓名；库中没有人脸达到识别阈值时为 unknown

recognition_scorenumber

对姓名的置信度，0 至 1

detection_scorebbox

对人脸的置信度及其 xmin、ymin、xmax、ymax

messagecompanyprocess_time

successfully performed；人脸库；秒

状态码

代码	含义
413	文件超过 2 MB
415	不支持的文件格式
420、421、422	必填字段缺失、无效或格式错误；parameter 指明字段
423	图像中未找到人脸
424	找到多张脸；请使用 /multi
427	演示库不允许此操作
428、429	导出或导入失败

详情

实测

指标	结果
正面人脸	98 至 99%
偏转 15° 以内	95 至 97%
偏转 30° 以内	85 至 90%
耗时，检测	0.2 至 0.3 秒
耗时，识别一张脸	0.4 至 0.6 秒

限制

• 人脸占画面 15% 以上时效果最佳。
• 正面偏转 15° 以内，双眼可见，不戴墨镜或口罩；不建议使用侧脸。
• 光线、清晰度、表情、年龄变化和面部饰物都会降低分数。
• 人脸库越大识别越慢；请导出备份并删除过时记录。

数据处理

处理后不保留图像；只在您的人脸库中加密保存人脸特征。生物特征数据依 GDPR 与 PDPA 需取得当事人明确同意，且适用删除权：/remove 可按要求删除某人。