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_numb	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).
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_orientedetection	String	Optional	Determines if image rotation is allowed for face detection when no face is found in `image_ref[x]`. Values: `"1"` (enable rotation), `"0"` (disable, default).
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).
biz_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:	Missing a required parameter. `<key>` indicates the missing parameter.	No
400	BAD_ARGUMENTS:	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:	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:	No face detected in the image for `<param>` (e.g., `image_ref1`). Only the first problematic parameter is reported.	No
400	INVALID_IMAGE_SIZE:	Image for `<param>` exceeds size limits (e.g., pixel dimensions > 4096px). Only the first invalid parameter is reported.	No
403	AUTHORIZATION_ERROR:	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