Describe

The server requests the Raw-GetToken interface to obtain the token parameter, which serves as the imported parameter for calling the js-sdk.

Call URL

Singapore: https://api-sgp.megvii.com/facoid/lite/raw/get_token
Note:
- In the production environment, use HTTPS for communication. HTTP is insecure and poses security risks; do not use it in production.
- Using HTTP in production will not guarantee service reliability.

Call Method

Method: POST
Format: Request in form-data format.

Parameters

Parameters must be passed in form-data format. Below is a summary table:

Parameter	Type	Required/Optional	Description
api_key	String	Required	API key for calling this API.
api_secret	String	Required	The secret of the api_key for calling this API.
biz_no	String	Optional	Used to mark a verification process (max length 128 bytes). Use the same `biz_no` for APIs in a single verification process (e.g., Raw-GetTokenFlash, Raw-GetResultFlash), and different `biz_no` for different processes.
color_number	Int	Optional	Number of lighting colors during the flash sensor face ID process. Allowed values: `4`, `6`, `8`. Recommended: `6`.
liveness_preferences	String	Optional	Sets the strictness level of live detection. Options: `"none"` (Quick Mode, default).
language	String	Optional	This parameter is optional, and the page prompt language can be switched through this parameter,0: English (default),1: Chinese
procedure_type	String	Optional	Specifies the live detection method. Only supported value: `"raw_flash"` (flash sensor face ID).
comparison_type	String	Required	Comparison method. Options: `"0"` (face comparing, compares with user-provided photo in `image_ref[x]`). Note: If the appkey lacks face comparing permission, this will return error 403 (AUTHORIZATION_ERROR: Denied).
uuid	String	Required	Unique ID for the user (max 512 bytes), used if no reference data is provided for comparison. Use the same ID for comparison requests from the same user to improve result tracking and reporting.
image_ref[x]	File	Required	User-provided reference face photos. `x` can be `1` or `2` (e.g., `image_ref1`, `image_ref2`). Max 2 photos. Errors: `400 (NO_FACE_FOUND)` if no face is detected, `400 (MULTIPLE_FACES)` if multiple faces found in any image.
multi_oriented_detection	String	Optional	This parameter specifies whether to rotate the photos in image_ref [x ] by 90, 180, and 270 degrees for face detection if no face is detected. The valid values of this parameter are "1" and "0" (default is "0"). 1: Rotate. 0: Do not rotate. Other value: The error code 400 (BAD_ARGUMENTS) is returned. Note: Setting this parameter to 1 might increase the false positive rate of face detection. If your business scenario does not contain or contain few photos with different orientations, you can ignore this parameter.
fail_when_ref_multiple_faces	String	Optional	This parameter specifies whether to immediately return an error code if multiple faces are detected in the face reference photos (image_ref[x]). Valid values: 1: Immediately return error code 400 (MULTIPLE_FACES). 0: Use the largest face in the photo for comparison. Note: The default value of this parameter is "1".
max_upload_times	Int	Required	This parameter is used to set the maximum number of uploads, with an allowed setting range of 2 - 5 times. It is recommended to set it to 5 (times).
life_time	Int	Required	This parameter is used to set the valid period of the token, with an allowed setting range of 5 - 1440 (unit: minutes). This parameter determines the valid period of the query results. It is recommended to set it to 60 (minutes).
return_multifaces_tag	String	Optional	This parameter specifies whether to return the multiple faces tag. 0: Do not return (default) 1: Return
face_occlusion_detection	String	Optional	Enables facial occlusion detection. Values: `"0"` (disabled, default), `"1"` (enabled; liveness check fails if occlusion occurs).

Notes on parameters:

For image_ref[x]: If no face is found or multiple faces are detected, the first problematic image triggers the error (e.g., image_ref1).
For comparison_type: Only "0" is valid; other values return error 400 (BAD_ARGUMENTS).

API Response

Returns a JSON string. Fields:

Field	Type	Description
request_id	String	Unique string to distinguish each request. Always returned except for error 404 (API_NOT_FOUND).
biz_no	String	Returned only if `biz_no` was set in the request. Value matches the input `biz_no`.
time_used	Int	Time taken for the entire request in milliseconds. Always returned except for error 404 (API_NOT_FOUND).
token	String	Returned only on success. Used as a parameter for the Raw-ValidateFlash interface (max 1024 bytes). Note: Default validity period is 1 hour.
error_message	String	Returned only on failure. Describes the error (see Error Code List below). Not present on success.

Error Code List

Below are common and specific errors. All errors return JSON except where noted.

Universal Errors

HTTP Status Code	Error Message	Description	Is it billed?
403	AUTHENTICATION_ERROR	Invalid signature.	No
403	CONCURRENCY_LIMIT_EXCEEDED	Concurrency exceeds the limit.	No
400	MISSING_ARGUMENTS:<key>	Missing a required parameter. `<key>` indicates the missing parameter.	No
400	BAD_ARGUMENTS:<key>	Error parsing a parameter (e.g., non-numeric string where number expected, or length too long). `<key>` indicates the invalid parameter.	No
400	IMAGE_ERROR_UNSUPPORTED_FORMAT:<param>	Image for `<param>` (e.g., `image_ref1`) cannot be parsed (not an image file or corrupted data). Only the first invalid parameter is reported.	No
400	NO_FACE_FOUND:<param>	No face detected in the image for `<param>` (e.g., `image_ref1`). Only the first problematic parameter is reported.	No
400	INVALID_IMAGE_SIZE:<param>	Image for `<param>` exceeds size limits (e.g., pixel dimensions > 4096px). Only the first invalid parameter is reported.	No
403	AUTHORIZATION_ERROR:<reason>	Permission issue. `<reason>` values: `API_KEY_BE_DISCONTINUED` (api_key deactivated), `IP_NOT_ALLOWED` (IP blocked), `LIMIT_REACHED` (call limit reached for test keys), `MORE_RETRY_TIMES` (comparison retries exceeded), `NO_VERIFY_PERMISSION` (no face comparing permission), `DENIED` (no API permission).	No
404	API_NOT_FOUND	Called API does not exist.	No
413	Request Entity Too Large	Request size exceeds 20MB limit. Note: Returns plain text, not JSON.	No
500	INTERNAL_ERROR	Internal server error. Retry the request. If persistent, contact FaceID support.	No