Face Search

Search for the same face photos that have been added by face photos

1. Add face image

Code example:

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'

Response for add face success with one face in the image

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

Response for add face success with two faces in the image

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

Response for detecting face failed

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

Response for server error

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

Response for invalid image format

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

Response for image size larger than 2M

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

HTTP request

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

Request parameters

parameter	description
`img`	`string`, use base64 to encode the face image
`name`	`string`, information attached to the added face, less than 128 characters, combination of numbers and letters
`facedb`	`optional`, `string`, facedb ID. if you need open facedb, please contact business people to provide additional facedb info

Response format

fields	description
`status`	status code, if `status` is `OK`, successfully add face image
`message`	some message of the addition result `person_id`: this is the unique personal id which you have added `name`: the input personal name

Status code

status	description
`OK`	`charge`, successfully add face image, add face is free
`FACE_DETECT_FAILED`	`charge`, detect face failed
`IMAGE_INVALID_SIZE`	`free`, image larger than 2M
`IMAGE_INVALID_FORMAT`	`free`, invalid image format, image format should be one of jpeg/jpg/png/bmp
`INVALID_REQUEST`	`free`, invalid request parameters
`FAIL`	`free`, other errors

2. Search the same face

Code example:

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'

Response for get similar faces

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

Response for get no similar faces

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

Response for detecting face failed

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

Response for invalid image format

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

Response for image size larger than 2M

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

Response for server error

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

HTTP request

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

Request parameters

parameter	description
`img`	`string`, the base64 encode of the face image
`facedb`	`optional`, `string`, facedb ID. if you need open facedb, please contact business people to provide additional facedb info

Response format

fields description

status status code

message some message of the face search result
confidence: this is the confidence level of the searched face, the range is [0, 100]. Confidence greater than 80 will be listed, and maximum of 50 similar items will be listed. In actual situations, Confidence need set at around 95 points to ensure sufficient accuracy.
person_id: this is the unique personal id which you have added
name: the input personal info

Status code

status	description
`OK`	`charge`, success search the face image
`NO_SIMILAR_FACE`	`charge`, no similar face in db
`FACE_DETECT_FAILED`	`charge`, detect face failed
`IMAGE_INVALID_SIZE`	`free`, image larger than 2M
`IMAGE_INVALID_FORMAT`	`free`, invalid image format, image format should be one of jpeg/jpg/png/bmp
`INVALID_REQUEST`	`free`, invalid request parameters
`FAIL`	`free`, other errors

3. Delete face

Code example:

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'

Response for delete face success

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

Response for input person id not exist

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

Response for server error

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

HTTP request

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

Request parameters

parameter	description
`person_id`	`string`, `person id`
`facedb`	`optional`, `string`, facedb ID. if you need open facedb, please contact business people to provide additional facedb info

Response format

fields	description
`status`	status code
`message`	err description

Status code

status	description
`OK`	`free`, success delete face
`PERSON_ID_NOT_EXIST`	`free`, input person id not exist
`INVALID_REQUEST`	`free`, invalid request parameters
`FAIL`	`free`, other errors