# Description

This API adds a face to the specified face library.

# Request URL:

https://api-sgp.yljz.com/finauth/search/group/add
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	Face library identifier provided by the user.
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.
Required	user_id	string	User ID. Supports letters, digits, -%@#&_ . Length limit: 48B. (Recommended: mobile number or ID number) Example: user_01
Optional	user_data	string	Custom user info; no more than 128 characters.
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 error code 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

Field	Type	Description
request_id	String	A unique string to distinguish each request. This field is always returned unless a 404 (API_NOT_FOUND) or 403 (AUTHORIZATION_ERROR) occurs.
group_id	String	User-defined face library identifier. Empty if not defined.
time_used	Int	Total time consumed by the request in milliseconds. This field is always returned unless a 404 (API_NOT_FOUND) or 403 (AUTHORIZATION_ERROR) occurs.
error	String	Returned only when the request fails. See the error section below for details. Otherwise this field does not exist.
face_token	String	Face token added successfully.

Response Example

Example: success response

{
    "request_id": "1769739688,c3e156ca-789f-4568-a310-357dc9790d62",
    "time_used": 1900,
    "group_id": "YuanliStudent_01",
    "face_token": "1691157fa602e57087489b0462029a9c"
}

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.