人脸搜索

搜索已添加的相同人脸照片

1. 添加人脸图像

代码示例：

curl --location --request POST 'https://api.ekycpro.com/v1/addface' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-API-Key: AbcdEfgh' \
--data-urlencode 'img=BASE64_ENCODE_VALUE'

添加人脸成功的响应，图像中有一张人脸

{
  "status": "OK",
  "message": [
    {
      "name": "ID0",
      "person_id": "4fbd9474-e09f-4e7d-9a2f-06fa1167f67e"
    }
  ]
}

添加人脸成功的响应，图像中有两张人脸

{
  "status": "OK",
  "message": [
    {
      "name": "ID1",
      "person_id": "c4b38db9-0721-4703-bf4d-306d176dd455"
    },
    {
      "name": "ID2",
      "person_id": "2c8460fa-3a44-4250-9542-a1e523f21a26"
    }
  ]
}

检测人脸失败的响应

{
  "status": "FACE_DETECT_FAILED",
  "message": "check input image and retry"
}

服务器错误的响应

{
  "status": "FAIL",
  "message": "please try again later"
}

图像格式无效的响应

{
  "status": "IMAGE_INVALID_FORMAT",
  "message": "image format not support"
}

图像大小超过 2M 的响应

{
  "status": "IMAGE_INVALID_SIZE",
  "message": "image larger than 2M"
}

HTTP 请求

POST http://api.ekycpro.com/v1/addface

请求参数

参数	描述
`img`	`string`，使用 base64 编码的人脸图像
`name`	`string`，附加到添加的人脸的信息，长度不超过 128 个字符，由数字和字母组合
`facedb`	`optional`，`string`，facedb ID。如果需要打开 facedb，请联系业务人员提供额外的 facedb 信息

响应格式

字段	描述
`status`	状态码，如果`status`为`OK`，表示成功添加人脸图像
`message`	添加结果的一些消息 `person_id`：已添加的唯一个人 ID `name`：输入的个人名称

状态码

状态	描述
`OK`	`charge`，成功添加人脸图像，添加人脸免费
`FACE_DETECT_FAILED`	`charge`，检测人脸失败
`IMAGE_INVALID_SIZE`	`free`，图像大小超过 2M
`IMAGE_INVALID_FORMAT`	`free`，无效的图像格式，图像格式应为 jpeg/jpg/png/bmp 之一
`INVALID_REQUEST`	`free`，无效的请求参数
`FAIL`	`free`，其他错误

2. 搜索相同人脸

代码示例：

curl --location --request POST 'https://api.ekycpro.com/v1/searchface' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-API-Key: AbcdEfgh' \
--data-urlencode 'img=BASE64_ENCODE_VALUE'

获取相似人脸的响应

{
  "status": "OK",
  "message": [
    {
      "confidence": 100,
      "name": "NAME",
      "person_id": "154fa1b2-9a21-4e67-8ea3-075c76162900"
    },
    {
      "confidence": 80,
      "name": "",
      "person_id": "4fbd9474-e09f-4e7d-9a2f-06fa1167f67e"
    }
  ]
}

获取没有相似人脸的响应

{
  "status": "NO_SIMILAR_FACE",
  "message": "no similar face in db"
}

检测人脸失败的响应

{
  "status": "FACE_DETECT_FAILED",
  "message": "check input image and retry"
}

图像格式无效的响应

{
  "status": "IMAGE_INVALID_FORMAT",
  "message": "image format not support"
}

图像大小超过 2M 的响应

{
  "status": "IMAGE_INVALID_SIZE",
  "message": "image larger than 2M"
}

服务器错误的响应

{
  "status": "FAIL",
  "message": "please try again later"
}

HTTP 请求

POST http://api.ekycpro.com/v1/searchface

请求参数

参数	描述
`img`	`string`，人脸图像的 base64 编码
`facedb`	`optional`，`string`，facedb ID。如果需要打开 facedb，请联系业务人员提供额外的 facedb 信息

响应格式

字段	描述
`status`	状态码
`message`	人脸搜索结果的一些消息 `confidence`：搜索到的人脸的置信度，范围为[0, 100]。置信度大于 80 将被列出，最多列出 50 个相似项。在实际情况中，为确保足够的准确性，置信度需要设置在 95 左右。 `person_id`：已添加的唯一个人 ID `name`：输入的个人信息

状态码

状态	描述
`OK`	`charge`，成功搜索到人脸图像
`NO_SIMILAR_FACE`	`charge`，数据库中没有相似的人脸
`FACE_DETECT_FAILED`	`charge`，检测人脸失败
`IMAGE_INVALID_SIZE`	`free`，图像大小超过 2M
`IMAGE_INVALID_FORMAT`	`free`，无效的图像格式，图像格式应为 jpeg/jpg/png/bmp 之一
`INVALID_REQUEST`	`free`，无效的请求参数
`FAIL`	`free`，其他错误

3. 删除人脸

代码示例：

curl --location --request POST 'https://api.ekycpro.com/v1/delface' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-API-Key: AbcdEfgh' \
--data-urlencode 'person_id=personId'

删除人脸成功的响应

{
  "status": "OK",
  "message": "successfully deleted face"
}

输入的人员 ID 不存在的响应

{
  "status": "PERSON_ID_NOT_EXIST",
  "message": "check input person id"
}

服务器错误的响应

{
  "status": "FAIL",
  "message": "please try again later"
}

HTTP 请求

POST http://api.ekycpro.com/v1/delface

请求参数

参数	描述
`person_id`	`string`，`person id`
`facedb`	`optional`，`string`，facedb ID。如果需要打开 facedb，请联系业务人员提供额外的 facedb 信息

响应格式

字段	描述
`status`	状态码
`message`	错误描述

状态码

状态	描述
`OK`	`free`，成功删除人脸
`PERSON_ID_NOT_EXIST`	`free`，输入的人员 ID 不存在
`INVALID_REQUEST`	`free`，无效的请求参数
`FAIL`	`free`，其他错误