Face Search

Input requirements

• Image format must be jpg or jpeg

• Size of the input image must not surpass 5 MB with minimum resolution around 640x480 to ensure accuracy rate

• Face must take up at least ¼ of the total image area.

API Information

1. Create user on the system (to add index images)

Request Url

POST https://api.fpt.ai/vision/ekyc/facesearch/v4/create

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Body

FormData contains the collection name and user information (id, name)

Parameter	Requirement	Default	Description
collection	yes	(empty)	each collection will be indexed and searched separately.
id	yes		user id must be unique
name	yes		user display name

Sample Request

curl --location --request POST 'https://api.fpt.ai/vision/ekyc/facesearch/v4/create' \\

\--header 'api_key: xxxxxxxxxxxxxxxx' \\

\--form 'collection=test2' \\

\--form 'id=1234' \\

\--form 'name=Nam'

Response

JSON

{

"data": "User created/updated",

"code": "200"

}

Response Code

Code	meaning
200	User created/updated
412	Missing api_key, id, or name

Sample Response: Success

{

"data": "User created/updated",

"code": "200"

}

2. Index user images

Request Url

POST https://api.fpt.ai/vision/ekyc/facesearch/v4/add

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Body

FormData contains the collection name, user id, and face image

Parameter	Requirement	Default	Description
collection	yes	(empty)	each collection will be indexed and searched separately.
id	yes		user id (must already exist via /create)
file	yes		face image: multipart file upload (jpg/jpeg/png) or base64 encoded string
allow_id_card	no	false	true/1: allow ID card (CMND/CCCD) images. If false, photos detected as ID cards will be rejected

Sample Request

curl --location --request POST 'https://api.fpt.ai/vision/ekyc/facesearch/v4/add' \\

\--header 'api_key: xxxxxxxxxxxxxxxx' \\

\--form 'file=\@/path/to/photo.jpg' \\

\--form 'collection=test2' \\

\--form 'id=1234'

Response

JSON

{

"data": "Add photo success",

"code": "200"

}

Response Code

Code	meaning
200	Image indexed successfully
400	Invalid image format or invalid base64 string
404	User id not found (must create user first via /create)
406	Face covered with mask, hat, sunglasses, or too close to camera
407	No face detected / More than 1 face detected
410	Photo is ID card (when allow_id_card is not set)
412	Missing required parameter (api_key or id)

Sample Response: Success

{
    "data": "Add photo success",
    "code": "200"
}

Sample Response: Error

{
    "data": "No face detected",
    "code": "407"
}

{
    "data": "More than 1 faces detected",
    "code": "407"
}

{
    "data": "Photo is id card",
    "code": "410"
}

{
    "data": "Photo not contains full face, too close; wearing mask, sunglasses or hat",
    "code": "406"
}

3. Facesearch

Request Url

POST https://api.fpt.ai/vision/ekyc/facesearch/v4/search

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Body

FormData contains the collection name, the face image to be searched, and optional search parameters

Parameter	Requirement	Default	Description
collection	yes	(empty)	each collection will be indexed and searched separately.
file	yes		face image: multipart file upload (jpg/jpeg/png) or base64 encoded string
threshold	no	0.85	similarity threshold for a positive match (range 0-1)
lower_threshold	no		secondary threshold: if lower_threshold <= similarity < threshold, returns extra_data with the closest match instead of 404. Must be less than threshold
allow_id_card	no	false	true/1: allow ID card (CMND/CCCD) images
create	no	false	true/1: auto-create a new user (with generated UUID) when no match is found. The face image will be uploaded to S3 and indexed
only_largest_face	no	false	true/1: when multiple faces are detected, use only the largest face instead of returning an error
disable_validation	no	false	true/1: skip face quality validation (mask, hat, sunglasses check)

Sample Request

curl --location --request POST 'https://api.fpt.ai/vision/ekyc/facesearch/v4/search' \\

\--header 'api_key: xxxxxxxxxxxxxxxx' \\

\--form 'file=\@/path/to/search_photo.jpg' \\

\--form 'collection=test2' \\

\--form 'threshold=0.9'

Response

The response shape depends on the match result and the parameters used.

Response Code

Code	meaning
200	Search completed (match found, extra_data returned, or user auto-created)
400	Invalid image format or invalid base64 string
404	No matching face found
406	Face covered with mask, hat, sunglasses, or too close to camera
407	No face detected / More than 1 face detected (when only_largest_face is not set)
410	Photo is ID card (when allow_id_card is not set)
412	Missing required parameter (api_key)

Sample Response: Match found (similarity >= threshold)

{
    "data": {
        "id": "1234",
        "name": "Nam",
        "similarity": 0.9999998807907104
    },
    "code": "200"
}

Sample Response: Possible match (lower_threshold <= similarity < threshold)

Only returned when lower_threshold is provided. Note: the key is extra_data, not data.

{
    "extra_data": {
        "id": "1234",
        "name": "Nam",
        "similarity": 0.82
    },
    "code": "200"
}

Sample Response: Auto-created user (when create=true and no match found)

{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "new": true
    },
    "code": "200"
}

Sample Response: Error

{
    "data": "No face detected",
    "code": "407"
}

{
    "data": "Photo is id card",
    "code": "410"
}

{
    "data": "Not found",
    "code": "404"
}

{
    "data": "Photo not contains full face, too close; wearing mask, sunglasses or hat",
    "code": "406"
}

4. Remove face data (not delete the user)

Request Url

DELETE https://api.fpt.ai/vision/ekyc/facesearch/v4/delete_faces

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Body

FormData contains the collection name and user id

Parameter	Requirement	Default	Description
collection	no	(empty)	collection name.
id	yes		the id of user

Sample Request

curl --location --request DELETE 'https://api.fpt.ai/vision/ekyc/facesearch/v4/delete_faces' \
--header 'api_key: xxxxxx' \
--form 'collection="test1"' \
--form 'id="2"'

Response

JSON

{
    "data": "User faces deleted",
    "code": "200"
}

Response Code

Code	meaning
200	Faces delete success
404	User not found
412	Missing api_key

5. Delete user

Request Url

DELETE https://api.fpt.ai/vision/ekyc/facesearch/v4/delete

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Body

FormData contains the collection name and user id

Parameter	Requirement	Default	Description
collection	no	(empty)	collection name.
id	yes		the id of user

Sample Request

curl --location --request DELETE 'https://api.fpt.ai/vision/ekyc/facesearch/v4/delete' \
--header 'api_key: xxxxxxxx' \
--form 'collection="test2"' \
--form 'id="1234"'

Response

JSON

{
    "data": "User deleted",
    "code": "200"
}

Response Code

Code	meaning
200	User delete success
404	User not found
412	Missing api_key

6. List users in collection

Request Url

GET https://api.fpt.ai/vision/ekyc/facesearch/v4/list

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Params

Query string contains the collection name

Parameter	Requirement	Default	Description
collection	no	(empty)	The collection name to list users.

Sample Request

curl --location --request GET 'https://api.fpt.ai/vision/ekyc/facesearch/v4/list?collection=test1' \
--header 'api_key: xxxxxx' \

Response

JSON

{
    "data": [
        {
            "id": "1",
            "name": "Nguyen Van A"
        },
        {
            "id": "3",
            "name": "Nguyen Van B"
        }
    ],
    "code": "200"
}

Response Code

Code	meaning
200	Request success
412	Missing api_key

7. Delete collection

Request Url

DELETE https://api.fpt.ai/vision/ekyc/facesearch/v4/delete_collection

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Body

FormData contains the collection name

Parameter	Requirement	Default	Description
collection	no	(empty)	collection name.

Sample Request

curl --location --request DELETE 'https://api.fpt.ai/vision/ekyc/facesearch/v4/delete_collection' \
--header 'api_key: xxxxxx' \
--form 'collection="test1"'

Response

JSON

{
    "data": "Remove collection success",
    "code": "200"
}

Response Code

Code	meaning
200	Collection delete success
404	Collection not found
412	Missing api_key

8. Add vector directly

Add a pre-computed 512-dimensional embedding vector to an existing user, without uploading an image.

Request Url

POST https://api.fpt.ai/vision/ekyc/facesearch/v4/add_vector

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Body

FormData contains the user id and a JSON-encoded embedding vector

Parameter	Requirement	Default	Description
collection	no	(empty)	collection name.
id	yes		user id (must already exist via /create)
vector	yes		JSON string of a 512-dimensional float array, e.g. [0.12, -0.34, ...]

Sample Request

curl --location --request POST 'https://api.fpt.ai/vision/ekyc/facesearch/v4/add_vector' \
--header 'api_key: xxxxxxxx' \
--form 'collection="test2"' \
--form 'id="1234"' \
--form 'vector="[0.12, -0.34, 0.56, ...]"'

Response

JSON

{
    "data": "Add photo success",
    "code": "200"
}

Response Code

Code	meaning
200	Vector added successfully
404	User not found
412	Missing api_key, id, or vector

9. Search by vector

Search for a matching user using a pre-computed 512-dimensional embedding vector instead of an image.

Request Url

POST https://api.fpt.ai/vision/ekyc/facesearch/v4/search_vector

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Body

FormData contains the embedding vector and search parameters

Parameter	Requirement	Default	Description
collection	no	(empty)	collection name.
vector	yes		JSON string of a 512-dimensional float array
threshold	no	0.85	similarity threshold for a positive match (range 0-1)

Sample Request

curl --location --request POST 'https://api.fpt.ai/vision/ekyc/facesearch/v4/search_vector' \
--header 'api_key: xxxxxxxx' \
--form 'collection="test2"' \
--form 'vector="[0.12, -0.34, 0.56, ...]"' \
--form 'threshold=0.9'

Response

Sample Response: Match found

{
    "data": {
        "id": "1234",
        "name": "Nam",
        "similarity": 0.95
    },
    "code": "200"
}

Sample Response: No match

{
    "data": "Not found",
    "code": "404"
}

Response Code

Code	meaning
200	Match found
404	No matching face found
412	Missing api_key or vector

10. Search without face cropping

Search for a matching user using a pre-aligned/cropped face image. The image is used directly for feature extraction without face detection or alignment.

Request Url

POST https://api.fpt.ai/vision/ekyc/facesearch/v4/search_no_crop

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)

Request Body

FormData contains the pre-aligned face image and search parameters

Parameter	Requirement	Default	Description
collection	no	(empty)	collection name.
file	yes		pre-aligned face image (multipart file upload only, jpg/jpeg/png)
threshold	no	0.85	similarity threshold for a positive match (range 0-1)

Sample Request

curl --location --request POST 'https://api.fpt.ai/vision/ekyc/facesearch/v4/search_no_crop' \
--header 'api_key: xxxxxxxx' \
--form 'file=@/path/to/aligned_face.jpg' \
--form 'collection="test2"' \
--form 'threshold=0.9'

Response

Sample Response: Match found

{
    "data": {
        "id": "1234",
        "name": "Nam",
        "similarity": 0.95
    },
    "code": "200"
}

Sample Response: No match

{
    "data": "Not found",
    "code": "404"
}

Response Code

Code	meaning
200	Match found
400	Invalid image format
404	No matching face found
412	Missing api_key or file

11. Extract face embedding vector (FaceMatch)

Extract a 512-dimensional face embedding vector from an image. Supports multiple model versions (FaceMatch v3, v4). Useful for external comparison or storing vectors separately.

Request Url

POST https://api.fpt.ai/vision/ekyc/facesearch/v4/extract_from_fm

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)
facematch_version	No	v3	model version for feature extraction: v3, v4, or none

Request Body

FormData contains the face image and optional parameters

Parameter	Requirement	Default	Description
file	yes		face image: multipart file upload (jpg/jpeg/png) or base64 encoded string
allow_id_card	no	false	true/1: allow ID card images
only_largest_face	no	false	true/1: use only the largest face when multiple faces detected
disable_validation	no	false	true/1: skip face quality validation

Sample Request

curl --location --request POST 'https://api.fpt.ai/vision/ekyc/facesearch/v4/extract_from_fm' \
--header 'api_key: xxxxxxxx' \
--header 'facematch_version: v4' \
--form 'file=@/path/to/photo.jpg'

Response

Sample Response: Success

{
    "data": {
        "vector": [0.0123, -0.0456, 0.0789, "... (512 floats)"]
    },
    "code": "200",
    "message": "successful"
}

Response Code

Code	meaning
200	Vector extracted successfully
400	Invalid image format or invalid base64 string
406	Face covered with mask, hat, sunglasses, or too close to camera
407	No face detected / More than 1 face detected (when only_largest_face is not set)
410	Photo is ID card (when allow_id_card is not set)
412	Missing api_key

12. Extract face embedding vector without cropping (FaceMatch)

Extract a 512-dimensional face embedding vector from a pre-aligned/cropped face image without performing face detection or alignment.

Request Url

POST https://api.fpt.ai/vision/ekyc/facesearch/v4/extract_no_crop_from_fm

Request Headers

Parameter	Requirement	Default	Description
api_key	Yes		your api_key (from console.fpt.ai)
facematch_version	No	v3	model version for feature extraction: v3, v4, or none

Request Body

FormData contains the pre-aligned face image

Parameter	Requirement	Default	Description
file	yes		pre-aligned face image (multipart file upload only, jpg/jpeg/png)

Sample Request

curl --location --request POST 'https://api.fpt.ai/vision/ekyc/facesearch/v4/extract_no_crop_from_fm' \
--header 'api_key: xxxxxxxx' \
--header 'facematch_version: v3' \
--form 'file=@/path/to/aligned_face.jpg'

Response

Sample Response: Success

{
    "data": {
        "vector": [0.0123, -0.0456, 0.0789, "... (512 floats)"]
    },
    "code": "200",
    "message": "successful"
}

Response Code

Code	meaning
200	Vector extracted successfully
400	Invalid image format
412	Missing api_key or file

---

Error Code Reference

Code	Description
200	Success
400	Invalid image format (not jpg/jpeg/png) or invalid base64 string
404	User/face not found or no match above threshold
406	Face quality check failed: covered with mask, hat, sunglasses, or too close
407	No face detected in image, or more than 1 face detected (use only_largest_face to override)
410	Image detected as ID card (CMND/CCCD). Use allow_id_card=true to override
412	Missing required parameter (e.g. api_key, id, name, vector)