# Description

This API performs 1:N face matching within the specified face library.

# Request URL:

https://api-sgp.yljz.com/finauth/search/group/search

Note: In production environments, please use HTTPS for communication. HTTP communication is considered insecure and poses security risks; therefore, it should not be used in production environments. Services using HTTP in production will not receive reliability guarantees.

# Calling Method

POST Note: Use form-data format for the request

# Request Parameters

Required	Parameter	Type	Description
Required	sign	String	The client signature for calling this API. For how to generate the signature, see the "Authentication Guide" document.
Required	sign_version	String	Signature algorithm version. Set to: hmac_sha1
Required	group_id	String	User-defined face library identifier.
Required (choose one)	image	String	Image base64 data If the image contains multiple faces, only the face with the largest area will be used. Supported formats: PNG, JPG, JPEG, BMP, jfif. GIF is not supported.
	file	File	Image file, Supported formats: PNG, JPG, JPEG, BMP, jfif. GIF is not supported.
Optional	limit	int	Limits the number of results returned; returns the top limit results with the highest matching scores. Default: 1. Maximum: 100.
Optional	threshold	Float	In the response, only results with scores greater than threshold will be returned. Example: For face library size 0-100k 1e-3: confidence threshold at FAR (false acceptance rate) =1/1,000; recommended threshold 75 1e-4: confidence threshold at FAR=1/10,000; recommended threshold 80 1e-5: confidence threshold at FAR=1/100,000; recommended threshold 85 1e-6: confidence threshold at FAR=1/1,000,000; recommended threshold 90 For face library size 100k-5,000k 1e-3: confidence threshold at FAR=1/1,000; 80 1e-4: confidence threshold at FAR=1/10,000; 85 1e-5: confidence threshold at FAR=1/100,000; 90 1e-6: confidence threshold at FAR=1/1,000,000; 95
Optional	multi_oriented_detection	String	Enables rotation detection for the image parameter. When no face is detected in the provided image, whether to try rotating the image by 90°, 180°, and 270° and then detect again. Allowed values are only "1" or "0" (default: "0"): "1": Enable rotation detection (enabling will increase API call time) "0": Disable rotation detection Other values: return HTTP 400 (BAD_ARGUMENTS) Note: Setting this parameter to 1 may slightly increase the probability of false face detection. If your business scenario does not include non-upright face images (or the probability is extremely low), it is recommended not to set this parameter.

# Response Fields

The API returns a JSON string.

Field	Type	Description
time_used	Int	Total time consumed by the request in milliseconds.
request_id	String	A unique string to distinguish each request.
error	String	Returned only when the request fails. See the error section below for details. Otherwise this field does not exist.
result	array	Search results.
face_token	string	Face token.
group_id	string	Face database ID.
score	float	Score.

Response Example

Example: success response

{
    "request_id": "1769742796,8628c588-244c-434e-a423-5fa8d3c5a74a",
    "time_used": 705,
    "result": [
        {
            "face_token": "0b25c78e8c62976767d190b0c5490af0",
            "group_id": "test_002",
            "score": 97.80590807301392
        }，
        {
            "face_token": "0b25c78e8c62976767d190b0c5490af0",
            "group_id": "test_002",
            "score": 96.80590807301392
        }
    ]
}

Example: error response

{
    "request_id": "1769684828,e483ae63-913b-4e32-9068-3719cce59570",
    "time_used": 15,
    "error": "INVALID_GROUP_ID"
}

# error_message Errors

ERROR_MESSAGE specific to this API

HTTP Status Code	Error	Description
400	INVALID_OUTER_ID	Face library does not exist.
400	NO_FACE_FOUND	No face found.