👤🔍 面部识别 API

0.1-0.3 IC每次请求

✅ 活跃🪪 eKYC

概述

艾艾普面部识别 API 是一个全面的面部识别解决方案，提供面部检测、识别、比对和数据库管理功能。我们的 API 基于最先进的深度学习模型构建，为安全、身份验证和身份验证等各种用例提供高精度和快速的处理。

试用演示！

Face Recognition API Demo

Test our face recognition endpoints with real-time results

API Key

Log in to use your API keys or Create an account

Base URL *

Current Endpoint

Endpoint changes based on selected tab

cURL Command

Recognizes the most prominent face in an image and matches it against your company's face database.

Upload Image *

Supported: JPG, JPEG, PNG (max 2MB)

Company Name *

主要特点

核心功能

• 面部检测: 在图像中检测具有边界框坐标的单个或多个面部
• 面部识别: 从您的自定义面部数据库中识别已知个人
• 面部比对: 比对两个面部以确定它们是否属于同一个人
• 数据库管理: 添加、删除、导入和导出面部记录
• 可配置阈值: 自定义检测和识别灵敏度
• 多面孔支持: 同时处理包含多个面部的图像

技术特点

• 高精度面部检测（正面人脸准确率 99% 以上）
• 快速处理时间（典型值为 0.3-1.0 秒）
• 支持各种图像格式（JPEG、JPG、PNG）
• 最大文件大小：2MB
• 公司专属面部数据库
• 基于分数匹配，具有可配置阈值
• RESTful API，易于集成

入门

先决条件

• API 密钥: 从 艾艾普 API 门户 获取
• 公司账户: 注册您的公司以进行面部数据库管理
• 图像要求:
  • 格式: JPEG, JPG, PNG
  • 最大尺寸: 2MB
  • 最小分辨率: 600x400 像素
  • 最小人脸尺寸: 112x112 像素

快速入门示例

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"

如何获取 API 密钥？

请访问 API 密钥管理 页面查看您现有的 API 密钥或请求新密钥。

API 端点

识别端点

端点	方法	描述	费用
/v3/store/ekyc/face-recognition/single	POST	识别最显著的人脸	0.3 IC

| /v3/store/ekyc/face-recognition/multi | POST | 识别图像中的所有人脸 | 0.3 IC | | /v3/store/ekyc/face-recognition/add | POST | 将新面孔添加到数据库 | 0.1 IC | | /v3/store/ekyc/face-recognition/remove | POST | 从数据库中删除面孔 | 0 IC | | /v3/store/ekyc/face-recognition/check | POST | 检查数据库状态 | 0.3 IC | | /v3/store/ekyc/face-recognition/import | POST | 导入面部特征 (CSV) | 0 IC | | /v3/store/ekyc/face-recognition/export | POST | 导出面部特征 | 0 IC |

检测端点

端点	方法	描述	费用
/v3/store/ekyc/face-detection/single	POST	检测带有边界框的单个人脸	0.3 IC
/v3/store/ekyc/face-detection/multi	POST	检测图像中的所有人脸	0.3 IC

比对端点

端点	方法	描述	费用
/v3/store/ekyc/face-comparison	POST	比对两个人脸以确定相似度	0.3 IC

配置端点

端点	方法	描述	费用
/v3/store/ekyc/face-recognition/config	POST	配置检测/识别阈值	0 IC
/v3/store/ekyc/face-recognition/password/change	POST	更改公司密码	0 IC

管理员端点

端点	方法	描述	费用
/v3/store/ekyc/face-recognition/admin/import	POST	管理员：导入特征	0 IC
/v3/store/ekyc/face-recognition/admin/export	POST	管理员：导出特征	0 IC
/v3/store/ekyc/face-recognition/admin/config	POST	管理员：配置阈值	0 IC
/v3/store/ekyc/face-recognition/admin/check	POST	管理员：检查数据库	0 IC
/v3/store/ekyc/face-recognition/admin/password/change	POST	管理员：更改密码	0 IC

---

API 参考

识别端点

单个人脸识别

端点: POST /v3/store/ekyc/face-recognition/single

识别图像中最显著的人脸，并将其与您公司的面部数据库进行匹配。

请求参数:

参数	类型	是否必填	描述
file	文件	是	图像文件 (JPEG, JPG, PNG, 最大 2MB)
company	字符串	是	您的公司标识符

响应格式:

{
  "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
}

响应字段:

• name: 识别出的人名（如果未匹配到则为“unknown”）
• recognition_score: 识别置信度 (0-1)
• detection_score: 面部检测置信度 (0-1)
• bbox: 人脸边界框坐标
• process_time: 处理时间（秒）

示例:

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

---

多人脸识别

端点: POST /v3/store/ekyc/face-recognition/multi

识别图像中的所有人脸，并为检测到的每个人脸返回一个结果数组。

请求参数:

参数	类型	是否必填	描述
file	文件	是	图像文件 (JPEG, JPG, PNG, 最大 2MB)
company	字符串	是	您的公司标识符

响应格式:

{
  "message": "successfully performed",
  "company": "YOUR_COMPANY",
  "faces": [
    {
      "name": "John Doe",
      "recognition_score": 0.8523,
      "detection_score": 0.9998,
      "bbox": {
        "xmin": 154.39,
        "ymin": 155.49,
        "xmax": 255.45,
        "ymax": 282.88
      }
    },
    {
      "name": "Jane Smith",
      "recognition_score": 0.7891,
      "detection_score": 0.9995,
      "bbox": {
        "xmin": 350.12,
        "ymin": 180.34,
        "xmax": 450.67,
        "ymax": 310.23
      }
    }
  ],
  "process_time": 0.6234
}

示例:

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

---

添加面孔到数据库

端点: POST /v3/store/ekyc/face-recognition/add

将新面孔添加到您公司的识别数据库。这会注册一个人以供将来识别。

请求参数:

参数	类型	是否必填	描述
file	文件	是	清晰的面部图像 (JPEG, JPG, PNG, 最大 2MB)
company	字符串	是	您的公司标识符
name	字符串	是	用于标识的个人姓名
password	字符串	是	用于身份验证的公司密码

响应格式:

{
  "message": "successfully performed",
  "company": "YOUR_COMPANY",
  "name": "John Doe",
  "face_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "detection_score": 0.9998
}

响应字段:

• face_id: 添加的面孔的唯一标识符
• detection_score: 面部图像的质量分数
• name: 注册的个人姓名

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/add \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@john_doe.jpg" \
  -F "company=iApp" \
  -F "name=John Doe" \
  -F "password=iApp"

演示密码

对于演示公司“iApp”，密码是“iApp”。您可以使用此密码来测试面部识别 API 端点。

最佳实践:

• 使用清晰、正面的面部图像
• 确保光线良好
• 避免模糊或低质量图像
• 每张图片只有一个人脸
• 人脸应面向相机

---

从数据库中删除面孔

端点: POST /v3/store/ekyc/face-recognition/remove

从您公司的数据库中删除面孔记录。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	您的公司标识符
name	字符串	是	要删除的个人姓名
password	字符串	是	用于身份验证的公司密码
face_id	字符串	否	要删除的特定面孔 ID（如果存在多个条目）

响应格式:

{
  "message": "face removed successfully",
  "company": "YOUR_COMPANY",
  "name": "John Doe",
  "removed_count": 1
}

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/remove \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "name=John Doe" \
  -F "password=iApp"

使用特定面孔 ID:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/remove \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "name=John Doe" \
  -F "face_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -F "password=iApp"

---

检查面部数据库

端点: POST /v3/store/ekyc/face-recognition/check

检查您公司面部数据库的状态和内容。返回统计信息，并可选择导出报告文件。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	您的公司标识符
password	字符串	是	用于身份验证的公司密码
save_file	字符串	否	设置为 "True" 或 "1" 可导出报告文件

响应格式（无文件导出）:

{
  "message": "successfully performed",
  "company": "YOUR_COMPANY",
  "total_faces": 145,
  "total_persons": 145,
  "database_size": "2.3 MB",
  "last_updated": "2025-01-15T10:30:00Z"
}

响应格式（带文件导出）:

返回一个 CSV 文件，其中包含面部数据库报告。

示例:

# 获取数据库统计信息
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/check \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp"

# 导出数据库报告
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/check \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp" \
  -F "save_file=True" \
  -o database_report.csv

---

导入面部特征

端点: POST /v3/store/ekyc/face-recognition/import

将预先计算的面部特征从 CSV 文件导入到您公司的数据库中。适用于批量导入或数据库迁移。

请求参数:

参数	类型	是否必填	描述
file	文件	是	包含面部特征的 CSV 文件
company	字符串	是	您的公司标识符
password	字符串	是	用于身份验证的公司密码

CSV 文件格式:

CSV 文件应包含面部特征向量，列包括：name、face_id、feature_vector（逗号分隔的浮点数值）。

响应格式:

{
  "message": "successfully performed",
  "company": "YOUR_COMPANY",
  "imported_count": 50,
  "failed_count": 0,
  "total_processed": 50
}

示例:

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

注意: 演示账户不支持导入。

---

导出面部特征

端点: POST /v3/store/ekyc/face-recognition/export

将您公司数据库中的面部特征导出到文件。支持 CSV 和 Excel 格式。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	您的公司标识符
password	字符串	是	用于身份验证的公司密码
type_file	字符串	是	导出格式：“csv”或“excel”

响应:

返回一个包含导出的面部特征的文件下载。

示例:

# 导出为 CSV
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/export \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp" \
  -F "type_file=csv" \
  -o face_features.csv

# 导出为 Excel
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/export \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp" \
  -F "type_file=excel" \
  -o face_features.xlsx

注意: 演示账户不支持导出。

---

检测端点

单个人脸检测

端点: POST /v3/store/ekyc/face-detection/single

检测图像中最显著的人脸，并返回边界框坐标，而不执行识别。

请求参数:

参数	类型	是否必填	描述
file	文件	是	图像文件 (JPEG, JPG, PNG, 最大 2MB)
company	字符串	否	可选的公司标识符

响应格式:

{
  "message": "successfully performed",
  "detection_score": 0.9998,
  "bbox": {
    "xmin": 154.39,
    "ymin": 155.49,
    "xmax": 255.45,
    "ymax": 282.88
  },
  "process_time": 0.2134
}

示例:

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

---

多人脸检测

端点: POST /v3/store/ekyc/face-detection/multi

检测图像中的所有人脸，并返回每个人脸的边界框坐标，而不执行识别。

请求参数:

参数	类型	是否必填	描述
file	文件	是	图像文件 (JPEG, JPG, PNG, 最大 2MB)
company	字符串	否	可选的公司标识符

响应格式:

{
  "message": "successfully performed",
  "faces": [
    {
      "detection_score": 0.9998,
      "bbox": {
        "xmin": 154.39,
        "ymin": 155.49,
        "xmax": 255.45,
        "ymax": 282.88
      }
    },
    {
      "detection_score": 0.9995,
      "bbox": {
        "xmin": 350.12,
        "ymin": 180.34,
        "xmax": 450.67,
        "ymax": 310.23
      }
    }
  ],
  "total_faces": 2,
  "process_time": 0.3567
}

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-detection/multi \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@group_photo.jpg"

---

比对端点

比对两个人脸

端点: POST /v3/store/ekyc/face-comparison

比对两个人脸图像，以确定它们是否属于同一个人。返回一个相似度分数。

请求参数:

参数	类型	是否必填	描述
file1	文件	是	第一张面部图像 (JPEG, JPG, PNG, 最大 2MB)
file2	文件	是	第二张面部图像 (JPEG, JPG, PNG, 最大 2MB)
company	字符串	否	可选的公司标识符
min_score	浮点数	否	最小相似度阈值 (0-1)

响应格式:

{
  "message": "successfully performed",
  "status": {
    "face1_detected": true,
    "face2_detected": true,
    "match": true
  },
  "similarity_score": 0.8734,
  "comparison_score": 0.8734,
  "face1_bbox": {
    "xmin": 154.39,
    "ymin": 155.49,
    "xmax": 255.45,
    "ymax": 282.88
  },
  "face2_bbox": {
    "xmin": 180.23,
    "ymin": 170.12,
    "xmax": 280.56,
    "ymax": 295.34
  },
  "process_time": 0.5423
}

响应字段:

• match: 布尔值，指示面部是否匹配（基于阈值）
• similarity_score: 面部之间的相似度分数 (0-1)
• status: 两个面部的检测状态
• face1_bbox, face2_bbox: 检测到的面部的边界框

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-comparison \
  -H "apikey: YOUR_API_KEY" \
  -F "file1=@person1.jpg" \
  -F "file2=@person2.jpg"

使用最小分数阈值:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-comparison \
  -H "apikey: YOUR_API_KEY" \
  -F "file1=@person1.jpg" \
  -F "file2=@person2.jpg" \
  -F "min_score=0.8"

---

配置端点

配置阈值

端点: POST /v3/store/ekyc/face-recognition/config

为您的公司配置检测和识别分数阈值。这些阈值决定了成功进行面部检测和识别所需的最低置信度分数。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	您的公司标识符
password	字符串	是	用于身份验证的公司密码
detection	浮点数	否	检测阈值（0-100 或 0-1）
comparison	浮点数	否	比对阈值（0-100 或 0-1）
recognition	浮点数	否	识别阈值（0-100 或 0-1）

响应格式:

{
  "message": "the minimum score of detection, comparison and recognition has been successfully configured.",
  "company": "YOUR_COMPANY",
  "detection_score": 0.75,
  "comparison_score": 0.80,
  "recognition_score": 0.85
}

示例:

# 设置所有阈值
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/config \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp" \
  -F "detection=75" \
  -F "comparison=80" \
  -F "recognition=85"

# 获取当前阈值（省略分数参数）
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/config \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp"

# 仅设置识别阈值
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/config \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp" \
  -F "recognition=90"

阈值指南:

• 检测 (默认约 0.75): 人脸检测的最低置信度

  • 较低：检测到更多人脸（可能包含误报）
  • 较高：仅检测清晰的人脸（可能遗漏某些人脸）

• 比对 (默认约 0.80): 人脸匹配的最低相似度

  • 较低：更宽松的匹配（可能匹配不同的人）
  • 较高：更严格的匹配（可能拒绝同一个人）

• 识别 (默认约 0.85): 个人身份识别的最低置信度

  • 较低：更宽松的识别（可能误识别）
  • 较高：更严格的识别（可能无法识别）

注意: 演示账户不支持配置。

---

更改密码

端点: POST /v3/store/ekyc/face-recognition/password/change

更改您公司的 API 身份验证密码。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	您的公司标识符
old_password	字符串	是	当前密码
new_password	字符串	是	新密码（必须不同）

响应格式:

{
  "message": "Setting new password completed."
}

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/password/change \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "old_password=current_password" \
  -F "new_password=new_secure_password"

注意: 演示账户不支持更改密码。

---

管理员端点

管理员端点需要特殊管理员权限，普通用户无法使用。

管理员：导入特征

端点: POST /v3/store/ekyc/face-recognition/admin/import

将面部特征导入演示数据库（仅限管理员）。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	必须为 "admin"
password	字符串	是	管理员密码
file	文件	是	包含面部特征的 CSV 文件

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/import \
  -H "apikey: YOUR_API_KEY" \
  -F "company=admin" \
  -F "password=admin_password" \
  -F "file=@features.csv"

---

管理员：导出特征

端点: POST /v3/store/ekyc/face-recognition/admin/export

从演示数据库导出面部特征或创建备份（仅限管理员）。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	必须为 "admin"
password	字符串	是	管理员密码
type_file	字符串	是	导出格式：“csv”、“excel”或“backup”

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/export \
  -H "apikey: YOUR_API_KEY" \
  -F "company=admin" \
  -F "password=admin_password" \
  -F "type_file=backup" \
  -o backup.csv

---

管理员：配置阈值

端点: POST /v3/store/ekyc/face-recognition/admin/config

为管理员或演示账户配置分数阈值（仅限管理员）。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	"admin" 或 "demo"
password	字符串	是	管理员密码
detection	浮点数	否	检测阈值（0-100 或 0-1）
comparison	浮点数	否	比对阈值（0-100 或 0-1）
recognition	浮点数	否	识别阈值（0-100 或 0-1）

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/config \
  -H "apikey: YOUR_API_KEY" \
  -F "company=demo" \
  -F "password=admin_password" \
  -F "detection=70" \
  -F "recognition=80"

---

管理员：检查数据库

端点: POST /v3/store/ekyc/face-recognition/admin/check

检查管理员或演示数据库状态（仅限管理员）。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	"admin" 或 "demo"
password	字符串	是	管理员密码
save_file	字符串	否	设置为 "True" 或 "1" 可导出报告

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/check \
  -H "apikey: YOUR_API_KEY" \
  -F "company=demo" \
  -F "password=admin_password"

---

管理员：更改密码

端点: POST /v3/store/ekyc/face-recognition/admin/password/change

更改管理员或演示账户的密码（仅限管理员）。

请求参数:

参数	类型	是否必填	描述
company	字符串	是	"admin" 或 "demo"
old_password	字符串	是	当前管理员密码
new_password	字符串	是	新密码（必须不同）

示例:

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/admin/password/change \
  -H "apikey: YOUR_API_KEY" \
  -F "company=demo" \
  -F "old_password=current_admin_password" \
  -F "new_password=new_admin_password"

---

错误码

API 使用标准的 HTTP 状态码并返回详细的错误消息。

HTTP 状态码

状态码	描述
200	成功
404	端点未找到
405	方法不允许（请使用 POST）
413	请求实体过大（文件 > 2MB）
415	不支持的媒体类型（请使用 JPEG, JPG, PNG）
420	缺少必需参数
421	参数值无效
422	参数格式无效
423	图像中未检测到人脸
424	检测到多人脸（请使用 /multi 端点）
425	新密码与旧密码相同
426	需要管理员权限
427	演示账户不允许操作
428	数据库导出失败
429	导入失败

错误响应格式

{
  "message": "Error description",
  "error_code": 421,
  "parameter": "company"
}

常见错误

420 - 缺少必需参数

{
  "message": "Missing required parameter: company",
  "error_code": 420,
  "parameter": "company"
}

421 - 参数无效

{
  "message": "Invalid value for parameter: password",
  "error_code": 421,
  "parameter": "password"
}

423 - 未检测到人脸

{
  "message": "No face detected in the image",
  "error_code": 423
}

424 - 检测到多人脸

{
  "message": "Multiple faces detected. Please use /recog/multi endpoint",
  "error_code": 424
}

---

代码示例

Python

import requests

def recognize_face(image_path, api_key, company):
    """Recognize face in image"""
    url = "https://api.iapp.co.th/v3/store/ekyc/face-recognition/single"

    files = {
        'file': open(image_path, 'rb')
    }
    data = {
        'company': company
    }
    headers = {
        'apikey': api_key
    }

    response = requests.post(url, headers=headers, data=data, files=files)
    return response.json()

def add_face_to_database(image_path, api_key, company, name, password):
    """Add new face to database"""
    url = "https://api.iapp.co.th/v3/store/ekyc/face-recognition/add"

    files = {
        'file': open(image_path, 'rb')
    }
    data = {
        'company': company,
        'name': name,
        'password': password
    }
    headers = {
        'apikey': api_key
    }

    response = requests.post(url, headers=headers, data=data, files=files)
    return response.json()

def compare_faces(image1_path, image2_path, api_key):
    """Compare two faces"""
    url = "https://api.iapp.co.th/v3/store/ekyc/face-comparison"

    files = {
        'file1': open(image1_path, 'rb'),
        'file2': open(image2_path, 'rb')
    }
    headers = {
        'apikey': api_key
    }

    response = requests.post(url, headers=headers, files=files)
    return response.json()

# Usage examples
if __name__ == "__main__":
    API_KEY = "your_api_key"
    COMPANY = "your_company"

    # Recognize face
    result = recognize_face("photo.jpg", API_KEY, COMPANY)
    print(f"Recognized: {result['name']}")
    print(f"Confidence: {result['recognition_score']:.2%}")

    # Add face to database
    result = add_face_to_database(
        "john_doe.jpg",
        API_KEY,
        COMPANY,
        "John Doe",
        "your_password"
    )
    print(f"Added: {result['name']}")

    # Compare two faces
    result = compare_faces("face1.jpg", "face2.jpg", API_KEY)
    print(f"Match: {result['status']['match']}")
    print(f"Similarity: {result['similarity_score']:.2%}")

JavaScript (Node.js)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

async function recognizeFace(imagePath, apiKey, company) {
    const formData = new FormData();
    formData.append('file', fs.createReadStream(imagePath));
    formData.append('company', company);

    try {
        const response = await axios.post(
            'https://api.iapp.co.th/v3/store/ekyc/face-recognition/single',
            formData,
            {
                headers: {
                    'apikey': apiKey,
                    ...formData.getHeaders()
                }
            }
        );
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
}

async function addFaceToDatabase(imagePath, apiKey, company, name, password) {
    const formData = new FormData();
    formData.append('file', fs.createReadStream(imagePath));
    formData.append('company', company);
    formData.append('name', name);
    formData.append('password', password);

    try {
        const response = await axios.post(
            'https://api.iapp.co.th/v3/store/ekyc/face-recognition/add',
            formData,
            {
                headers: {
                    'apikey': apiKey,
                    ...formData.getHeaders()
                }
            }
        );
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
}

async function compareFaces(image1Path, image2Path, apiKey) {
    const formData = new FormData();
    formData.append('file1', fs.createReadStream(image1Path));
    formData.append('file2', fs.createReadStream(image2Path));

    try {
        const response = await axios.post(
            'https://api.iapp.co.th/v3/store/ekyc/face-comparison',
            formData,
            {
                headers: {
                    'apikey': apiKey,
                    ...formData.getHeaders()
                }
            }
        );
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
}

// Usage examples
(async () => {
    const API_KEY = 'your_api_key';
    const COMPANY = 'your_company';

    try {
        // Recognize face
        const result = await recognizeFace('photo.jpg', API_KEY, COMPANY);
        console.log('Recognized:', result.name);
        console.log('Confidence:', result.recognition_score);

        // Add face to database
        const addResult = await addFaceToDatabase(
            'john_doe.jpg',
            API_KEY,
            COMPANY,
            'John Doe',
            'your_password'
        );
        console.log('Added:', addResult.name);

        // Compare two faces
        const compareResult = await compareFaces('face1.jpg', 'face2.jpg', API_KEY);
        console.log('Match:', compareResult.status.match);
        console.log('Similarity:', compareResult.similarity_score);
    } catch (error) {
        console.error('Error:', error);
    }
})();

JavaScript (浏览器)

// Face Recognition Function
async function recognizeFace(fileInput, apiKey, company) {
    const formData = new FormData();
    formData.append('file', fileInput.files[0]);
    formData.append('company', company);

    try {
        const response = await fetch('https://api.iapp.co.th/v3/store/ekyc/face-recognition/single', {
            method: 'POST',
            headers: {
                'apikey': apiKey
            },
            body: formData
        });

        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error:', error);
        throw error;
    }
}

// Add Face to Database
async function addFaceToDatabase(fileInput, apiKey, company, name, password) {
    const formData = new FormData();
    formData.append('file', fileInput.files[0]);
    formData.append('company', company);
    formData.append('name', name);
    formData.append('password', password);

    try {
        const response = await fetch('https://api.iapp.co.th/v3/store/ekyc/face-recognition/add', {
            method: 'POST',
            headers: {
                'apikey': apiKey
            },
            body: formData
        });

        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error:', error);
        throw error;
    }
}

// Compare Two Faces
async function compareFaces(fileInput1, fileInput2, apiKey) {
    const formData = new FormData();
    formData.append('file1', fileInput1.files[0]);
    formData.append('file2', fileInput2.files[0]);

    try {
        const response = await fetch('https://api.iapp.co.th/v3/store/ekyc/face-comparison', {
            method: 'POST',
            headers: {
                'apikey': apiKey
            },
            body: formData
        });

        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error:', error);
        throw error;
    }
}

// HTML Example
/*
<input type="file" id="faceImage" accept="image/*">
<input type="text" id="company" placeholder="Company">
<button onclick="handleRecognize()">Recognize Face</button>

<script>
async function handleRecognize() {
    const fileInput = document.getElementById('faceImage');
    const company = document.getElementById('company').value;
    const apiKey = 'your_api_key';

    const result = await recognizeFace(fileInput, apiKey, company);
    console.log('Result:', result);
    alert(`Recognized: ${result.name}\nConfidence: ${result.recognition_score}`);
}
</script>
*/

PHP

<?php

class FaceRecognitionAPI {
    private $apiKey;
    private $baseUrl = 'https://api.iapp.co.th';

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    public function recognizeFace($imagePath, $company) {
        $curl = curl_init();

        curl_setopt_array($curl, array(
            CURLOPT_URL => $this->baseUrl . '/v3/store/ekyc/face-recognition/single',
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => 'POST',
            CURLOPT_POSTFIELDS => array(
                'file' => new CURLFile($imagePath),
                'company' => $company
            ),
            CURLOPT_HTTPHEADER => array(
                'apikey: ' . $this->apiKey
            ),
        ));

        $response = curl_exec($curl);
        $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
        curl_close($curl);

        if ($httpCode !== 200) {
            throw new Exception("API request failed with code: $httpCode");
        }

        return json_decode($response, true);
    }

    public function addFaceToDatabase($imagePath, $company, $name, $password) {
        $curl = curl_init();

        curl_setopt_array($curl, array(
            CURLOPT_URL => $this->baseUrl . '/v3/store/ekyc/face-recognition/add',
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => 'POST',
            CURLOPT_POSTFIELDS => array(
                'file' => new CURLFile($imagePath),
                'company' => $company,
                'name' => $name,
                'password' => $password
            ),
            CURLOPT_HTTPHEADER => array(
                'apikey: ' . $this->apiKey
            ),
        ));

        $response = curl_exec($curl);
        $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
        curl_close($curl);

        if ($httpCode !== 200) {
            throw new Exception("API request failed with code: $httpCode");
        }

        return json_decode($response, true);
    }

    public function compareFaces($image1Path, $image2Path) {
        $curl = curl_init();

        curl_setopt_array($curl, array(
            CURLOPT_URL => $this->baseUrl . '/v3/store/ekyc/face-comparison',
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => 'POST',
            CURLOPT_POSTFIELDS => array(
                'file1' => new CURLFile($image1Path),
                'file2' => new CURLFile($image2Path)
            ),
            CURLOPT_HTTPHEADER => array(
                'apikey: ' . $this->apiKey
            ),
        ));

        $response = curl_exec($curl);
        $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
        curl_close($curl);

        if ($httpCode !== 200) {
            throw new Exception("API request failed with code: $httpCode");
        }

        return json_decode($response, true);
    }

    public function detectFaces($imagePath, $multiplefaces = false) {
        $endpoint = $multiplefaces ? '/v3/store/ekyc/face-detection/multi' : '/v3/store/ekyc/face-detection/single';
        $curl = curl_init();

        curl_setopt_array($curl, array(
            CURLOPT_URL => $this->baseUrl . $endpoint,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => 'POST',
            CURLOPT_POSTFIELDS => array(
                'file' => new CURLFile($imagePath)
            ),
            CURLOPT_HTTPHEADER => array(
                'apikey: ' . $this->apiKey
            ),
        ));

        $response = curl_exec($curl);
        $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
        curl_close($curl);

        if ($httpCode !== 200) {
            throw new Exception("API request failed with code: $httpCode");
        }

        return json_decode($response, true);
    }
}

// Usage example
$api = new FaceRecognitionAPI('your_api_key');

try {
    // Recognize face
    $result = $api->recognizeFace('photo.jpg', 'your_company');
    echo "Recognized: " . $result['name'] . "\n";
    echo "Confidence: " . ($result['recognition_score'] * 100) . "%\n";

    // Add face to database
    $result = $api->addFaceToDatabase('john_doe.jpg', 'your_company', 'John Doe', 'your_password');
    echo "Added: " . $result['name'] . "\n";

    // Compare two faces
    $result = $api->compareFaces('face1.jpg', 'face2.jpg');
    echo "Match: " . ($result['status']['match'] ? 'Yes' : 'No') . "\n";
    echo "Similarity: " . ($result['similarity_score'] * 100) . "%\n";

    // Detect faces
    $result = $api->detectFaces('group_photo.jpg', true);
    echo "Total faces detected: " . $result['total_faces'] . "\n";

} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

cURL 示例

# 单个人脸识别
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=YOUR_COMPANY"

# 多人脸识别
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/multi \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@group_photo.jpg" \
  -F "company=YOUR_COMPANY"

# 添加面孔到数据库
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/add \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@john_doe.jpg" \
  -F "company=iApp" \
  -F "name=John Doe" \
  -F "password=iApp"

# 从数据库中删除面孔
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/remove \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "name=John Doe" \
  -F "password=iApp"

# 比对两个人脸
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-comparison \
  -H "apikey: YOUR_API_KEY" \
  -F "file1=@face1.jpg" \
  -F "file2=@face2.jpg" \
  -F "min_score=0.8"

# 检测单个人脸
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-detection/single \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@photo.jpg"

# 检测多人脸
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-detection/multi \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@group_photo.jpg"

# 配置阈值
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/config \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp" \
  -F "detection=75" \
  -F "recognition=85"

# 检查数据库
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/check \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp"

# 导出数据库 (CSV)
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/export \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp" \
  -F "type_file=csv" \
  -o face_database.csv

# 导出数据库 (Excel)
curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/export \
  -H "apikey: YOUR_API_KEY" \
  -F "company=iApp" \
  -F "password=iApp" \
  -F "type_file=excel" \
  -o face_database.xlsx

---

最佳实践

图像质量指南

为获得最佳面部识别准确率：

1. 图像分辨率

   • 最低：600x400 像素
   • 推荐：1024x768 像素或更高
   • 人脸应占据图像面积的至少 15-20%

2. 光照条件

   • 使用光线充足、均匀照明的面部
   • 避免强烈的阴影或逆光
   • 自然光或中性白光效果最佳
   • 避免极端光照条件

3. 面部位置

   • 首选正面视图（±15 度）
   • 双眼应可见
   • 面部应竖直
   • 避免极端角度或倾斜

4. 图像质量

   • 使用清晰、锐利的图像
   • 避免运动模糊
   • 最大限度地减少压缩伪影
   • 无滤镜或过度编辑

5. 面部覆盖

   • 避免佩戴太阳镜、口罩或遮挡物
   • 头发不应遮挡眼睛
   • 面部配饰最少
   • 面部特征清晰可见

数据库管理

1. 添加面孔

   • 每人使用多张照片（推荐 3-5 张）以提高准确性
   • 包括略有差异的照片（不同的表情、光照）
   • 确保注册时使用高质量图像
   • 使用描述性、唯一的姓名

2. 定期维护

   • 定期审查和清理数据库
   • 删除过时或重复的条目
   • 使用导出功能定期备份数据库
   • 监控数据库大小和性能

3. 安全性

   • 使用强密码
   • 定期更改密码
   • 限制对敏感操作的访问
   • 保护 API 密钥安全

性能优化

1. 图像预处理

   • 上传前调整大图像尺寸
   • 在不损失质量的情况下压缩图像
   • 裁剪以聚焦于面部区域
   • 转换为 RGB 格式

2. 批量操作

   • 使用导入/导出进行批量操作
   • 对失败的请求实现重试逻辑
   • 妥善处理超时
   • 监控 API 速率限制

3. 错误处理

   • 实现适当的错误处理
   • 记录错误以进行调试
   • 为失败提供用户反馈
   • 重试瞬时错误

阈值配置

1. 检测阈值

   • 从默认值 (0.75) 开始
   • 如果误报过多，则提高
   • 如果遗漏有效面孔，则降低
   • 使用您的典型图像质量进行测试

2. 识别阈值

   • 提高安全性（更严格的匹配）时，请使用默认值 (0.85)
   • 降低以便更宽松地进行识别
   • 根据用例要求进行调整

3. 比对阈值

   • 用于验证时，使用更高的阈值 (0.80-0.90)
   • 用于识别时，使用较低的阈值 (0.70-0.80)
   • 使用已知的匹配/非匹配对进行测试
   • 根据用例要求进行调整

---

用例

1. 门禁系统

使用面部识别进行物理或数字门禁：

• 员工考勤跟踪
• 楼宇门禁管理
• 安全区域身份验证
• 访客管理系统

实施:

1. 使用 /recog/add 注册员工面孔
2. 在入口点使用 /recog/single 进行实时识别
3. 为安全配置高识别阈值 (0.90+)
4. 记录带有时间戳的访问事件

2. 身份验证

为 KYC（了解您的客户）流程验证用户身份：

• 金融服务入职
• 政府服务身份验证
• 年龄验证
• 文件验证（比对身份证照片和自拍照）

实施:

1. 从身份证件中提取面部
2. 捕获实时自拍照
3. 使用 /compare 端点匹配面部
4. 根据风险承受能力设置比对阈值
5. 存储验证结果以供审计

3. 照片组织

根据面孔自动组织和标记照片：

• 个人照片库管理
• 活动照片分类
• 家庭相册
• 社交媒体应用程序

实施:

1. 使用 /detect/multi 在照片中查找所有人脸
2. 使用 /recog/multi 识别已知人员
3. 按检测到的人员对照片进行分组
4. 手动识别未知面孔

4. 安全和监控

监控和识别安全录像中的个人：

• 零售防损
• 公共安全监控
• VIP 身份识别
• 黑名单筛查

实施:

1. 从视频流中提取帧
2. 使用 /detect/multi 查找人脸
3. 使用 /recog/multi 识别相关人员
4. 对高置信度匹配发出警报
5. 存储检测日志以供审查

5. 客户体验

通过面部识别增强客户服务：

• VIP 客户识别
• 个性化购物体验
• 忠诚度计划集成
• 回头客识别

实施:

1. 征得同意后注册客户面孔
2. 在入口处使用 /recog/single 进行识别
3. 检索客户偏好和历史记录
4. 提供个性化服务
5. 尊重隐私和数据保护法规

---

限制和注意事项

技术限制

1. 图像大小

   • 最大文件大小：2MB
   • 超过限制的文件将返回 HTTP 413 错误

2. 人脸大小

   • 最低人脸尺寸：112x112 像素
   • 小于最小尺寸的人脸可能无法被检测到

3. 面部角度

   • 最佳：正面视图（±15 度）
   • 角度过大时准确率会下降

4. 图像质量

   • 低质量图像可能导致检测失败
   • 运动模糊会降低识别准确率

5. 数据库大小

   • 大型数据库可能会影响识别速度
   • 建议定期维护

性能注意事项

1. 处理时间

   • 典型值：每次请求 0.3-1.0 秒
   • 可能会因服务器负载而增加
   • 多人脸检测比单人脸检测花费的时间更长

2. 准确率因素

   • 图像质量
   • 光照条件
   • 面部角度和表情
   • 年龄变化
   • 面部配饰

3. 速率限制

   • 适用 API 速率限制
   • 队列系统管理高流量
   • 联系支持以获得更高限制

隐私和合规性

1. 数据保护

   • 处理后不存储图像
   • 面部特征在数据库中加密
   • 符合 GDPR 和 PDPA
   • 收集面部信息需获得用户同意

2. 道德使用

   • 仅用于合法目的
   • 尊重隐私权
   • 实现选择退出机制
   • 对面部识别的使用保持透明

3. 安全性

   • 保护 API 密钥
   • 对所有请求使用 HTTPS
   • 安全访问面部数据库
   • 定期进行安全审计

法规遵从

1. GDPR（欧洲）

   • 生物识别数据属于特殊类别数据
   • 需要明确同意
   • 适用于删除权
   • 需要进行数据保护影响评估

2. PDPA（泰国）

   • 生物识别数据需要同意
   • 通知数据主体目的
   • 实施安全措施
   • 允许数据主体权利

3. 其他法规

   • 检查当地法律法规
   • 获取必要的许可证
   • 实施所需的保障措施
   • 记录合规措施

---

准确率与性能

识别准确率

• 正面人脸: 98-99% 准确率
• 角度人脸 (±15°): 95-97% 准确率
• 角度人脸 (±30°): 85-90% 准确率
• 侧面视图: 准确率有限（不推荐）

处理速度

• 单个人脸检测: 0.2-0.3 秒
• 单个人脸识别: 0.4-0.6 秒
• 多人脸检测: 0.3-0.5 秒
• 多人脸识别: 0.5-1.0 秒
• 面部比对: 0.4-0.6 秒

注意：时间为典型值，可能因图像大小、服务器负载和网络延迟而异。

影响性能的因素

1. 图像质量

   • 分辨率越高 = 准确率越高，处理时间越长
   • 压缩伪影会降低准确率
   • 良好的光照对于准确率至关重要

2. 面部数据库大小

   • 数据库越大 = 识别时间略长
   • 最多 10,000 张人脸：影响最小
   • 超过 10,000 张人脸：考虑数据库优化

3. 网络条件

   • 文件上传时间会影响总响应时间
   • 使用适当的超时设置
   • 为网络故障实现重试逻辑

4. 服务器负载

   • 高峰时段可能需要更长的排队时间
   • 队列系统确保公平处理
   • 联系支持以获得专用资源

---

定价

API 端点定价

操作	端点	IC 费用	单位
单个人脸识别	/v3/store/ekyc/face-recognition/single	0.3 IC	每次请求
多人脸识别	/v3/store/ekyc/face-recognition/multi	0.3 IC	每次请求
添加面孔到数据库	/v3/store/ekyc/face-recognition/add	0.1 IC	每次请求
检查数据库	/v3/store/ekyc/face-recognition/check	0.3 IC	每次请求
单个人脸检测	/v3/store/ekyc/face-detection/single	0.3 IC	每次请求
多人脸检测	/v3/store/ekyc/face-detection/multi	0.3 IC	每次请求
比对面部	/v3/store/ekyc/face-comparison	0.3 IC	每次请求
移除面孔	/v3/store/ekyc/face-recognition/remove	0 IC	每次请求
导入特征	/v3/store/ekyc/face-recognition/import	0 IC	每次请求
导出特征	/v3/store/ekyc/face-recognition/export	0 IC	每次请求
配置阈值	/v3/store/ekyc/face-recognition/config	0 IC	每次请求
更改密码	/v3/store/ekyc/face-recognition/password/change	0 IC	每次请求

本地部署

对于高流量或敏感数据要求，请考虑本地部署：

• 无限 API 调用
• 数据不出您的基础设施
• 定制集成支持
• 专属技术支持
• 自定义阈值配置
• 自定义数据库管理

联系我们 了解本地部署许可和定价。

---

支持

文档

• API 参考: 完整的端点文档（本页）
• 集成指南: 特定语言的集成指南
• 代码示例: 可立即使用的代码样本
• 最佳实践: 优化和安全指南

技术支持

• 电子邮件: info@iapp.co.th
• 网站: https://iapp.co.th
• API 门户: https://iapp.co.th
• Discord 社区: 加入我们的 Discord

商务咨询

对于企业解决方案、定制集成或本地部署：

• 销售: sale@iapp.co.th
• 电话: 086-322-5858
• 联系表单: https://iapp.co.th/contact-us

---

更新日志

版本 1.3.0 (当前)

• 增强了多人脸识别准确率
• 改善了角度人脸的检测
• 添加了用于数据库管理的管理员端点
• 优化了处理速度
• 增强了错误处理和报告
• 添加了全面的 API 文档

版本 1.2.0

• 添加了面部比对端点
• 改进了识别阈值配置
• 增强了数据库导入/导出功能
• 添加了密码管理功能
• 性能优化

版本 1.1.0

• 添加了多人脸检测和识别
• 引入了可配置的分数阈值
• 增强了错误消息
• 添加了数据库管理功能
• 性能改进

版本 1.0.0

• 初始发布
• 单个人脸识别
• 面部检测
• 基本数据库管理

---

相关 API

• 泰国身份证 OCR: 从泰国身份证提取数据
• 人脸活度检测: 检测活体人脸而非照片
• 文档 OCR: 从文档中提取文本
• 护照 OCR: 从护照提取数据

---

© 2025 艾艾普科技有限公司。保留所有权利。

此 API 基于用户反馈和技术进步不断改进。请定期检查更新。