Access Documentation
Anti-Forgery Detection
Facial Image Compare
Facial Image Compare

# compare Anti-Forgery

# Version

5.0.0

# Description

This interface uploads the customer's image data and obtains the 1:1 face comparing result.

# Request URL

Singapore: https://api-sgp.yljz.com/finauth/v5/compare

Indonesia: https://api-idn.yljz.com/finauth/v5/compare

# Request Method

POST — Note: Use form-data format for the request.

# Permission

Only when the user has integrated the FinAuth product can the FinAuth Web APIs be called. Please consult FinAuth business personnel for the process of integrating FinAuth.

# Parameters

Required/Optional Parameter Type Description
Required sign String The customer's signature for calling this API. For the specific method of generating the signature, refer to the "Authentication Guide" document.
Required sign_version String The signature algorithm version number. Please pass: hmac_sha1.
Optional biz_no String Default is empty. The customer's business serial number; we recommend setting it to a unique serial string related to your business. It is returned to your server unchanged in the response, helping you confirm the ownership of the corresponding business. This field must not exceed 128 bytes.
Required compare_id String Compare Scene ID: the configuration related to this verification request can be set in the "Console Compare Scene", and the generated ID is used in the interface.
Required encryption_type String Whether to enable data encryption during transmission. For details, see the "Encryption Guide". 0: Disabled; 2: RSA.
Required image File Verify by uploading your own photo.
Required image_ref1 File The reference face photo provided by the application. If no face is found in image_ref1, error code 400 (NO_FACE_FOUND) is returned; if there are multiple faces in the image, the largest face is selected for comparison.
Optional uuid String The unique ID of the user corresponding to this recognition, no longer than 128 bytes. Continuously using the same ID for the same user facilitates result tracing and data report optimization.

# Return Values

Parameter category Parameter Type Description
#Basic return information request_id String The serial number of the API call.
biz_no String The business serial number passed in, returned unchanged.
time_used Int The time taken by the entire request, in milliseconds. This field is always returned.
error String Returned only when the request fails. See the Error code section for details; otherwise this field is not present.
#Status code result_code Int The status code of this verification result. Combine result_code and result_message to learn the specific result and reason:The 1000-series status codes indicate that the comparison is complete, liveness passed, and the comparison passed.The 2000-series status codes indicate that the comparison is complete, liveness passed, but the comparison failed.For other results, please reserve a handling scheme; we may continue to add error codes for possible future errors.
#Status code description result_message String Use this field to learn the specific reason. See the result_code & result_message table.
#Comparison result verification Json "ref1": the comparison result between the input image face and the uploaded image_ref1."confidence": Float, range [0,100]; a larger number indicates lower risk."thresholds": a set of reference confidence thresholds, Object type, containing the following Float fields, range [0,100]:"1e-3": confidence threshold for a risk of one in a thousand (corresponds to comparison strictness = Loose in the Console Compare Scene configuration)."1e-4": confidence threshold for a risk of one in ten thousand (corresponds to comparison strictness = Regular (default))."1e-5": confidence threshold for a risk of one in a hundred thousand (corresponds to comparison strictness = Strict)."1e-6": confidence threshold for a risk of one in a million (corresponds to comparison strictness = Very Strict).Note: The comparison reference threshold, configured via "comparison strictness" in the Console Compare Scene, directly affects the result_code. If confidence is greater than the configured comparison threshold, the comparison passes (result_code=1000); if less, the comparison fails (result_code=2000).
#Additional return information visual_attributes Json Additional attributes:"age": estimated age of the person being verified."gender": estimated gender of the person being verified; 0: male; 1: female."age_image_ref1": estimated age of reference face image ref1."gender_image_ref1": estimated gender of reference face image ref1; 0: male; 1: female.
verify_risk_info Json Comparison risk hint result:"verify_info_tags": Json type; indicates the comparison risk type of the liveness image.Note: This parameter is returned only when "comparison risk detection" is enabled in the Console Compare Scene.is_gender_risk (string): 0 means the gender prediction of the input image and image_ref1 is consistent; 1 means inconsistent.is_age_risk (string): 0 means the age prediction difference between the input image and image_ref1 is small; 1 means large (generally an age gap of 10 years or more, depending on the threshold setting).
face Json Returned when the image method is used; the attributes of the image to be verified:"quality": face quality."quality_threshold": face quality threshold."rect": face coordinates, json type."orientation": face orientation.

# Return Value Examples

Correct request return example

{
 "request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
 "biz_no":"",
 "time_used":1448,
 "result_code":1000,
 "result_message":"SUCCESS",
 "verification":{
 "ref1":{
 "confidence":86.63057,
 "thresholds":{
 "1e-3":62.168713,
 "1e-4":69.31534
 "1e-5":74.39926,
 "1e-6":78.038055
 }
 }
 },
 "face":{
 "quality":38.221,
 "quality_threshold":30.1,
 "rect":{
 "left":0.18,
 "top":0.18,
 "width":0.596,
 "height":0.596
 },
 "orientation":90
 },
 "visual_attributes":{
 "age":20,
 "gender":0,
 "age_image_ref1":38,
 "gender_image_ref":0,
 },
 "verify_risk_info":{
 "verify_info_tags":{
 "is_gender_risk":0,
 "is_age_risk":1,
 }
 } 
}

Failed request return example

{
 "error": "AUTHORIZATION_ERROR: INVALID_SIGN"
}

# result_code & result_message table

result_code result_message Meaning Billable
1000 SUCCESS Comparison verification succeeded. Yes; for detailed billing, consult business support.
2000 PASS_LIVING_NOT_THE_SAME After verification, the photo to be compared is not the same person as at least one of the other photos. Yes

# Error Code List

HTTP status code Error message Description
400 MISSING_ARGUMENTS: A required parameter is missing.
400 IMAGE_ERROR_UNSUPPORTED_FORMAT: The image for parameter cannot be parsed. It may not be an image file or the data is corrupted. is one of image_ref1 or image_ref2. Note: contains only one item, i.e. the first name that meets the condition.
400 NO_FACE_FOUND: No face was detected in the uploaded image_ref image. is one of image_ref1 or image. Note: contains only one item, i.e. the first name that meets the condition.
400 INVALID_IMAGE_SIZE: The uploaded image is too large — specifically, the pixel length or width exceeds 4096 pixels. is one of image_ref1 or image. Note: contains only one item, i.e. the first name that meets the condition.
400 LOW_QUALITY The image quality is too low.
400 MULTIPLE_FACES Multiple faces are present in the image.
400 KEY_NOT_FOUND encryption_type is enabled, but the encryption public key and decryption private key are not configured.
403 AUTHENTICATION_ERROR Invalid signature.
403 AUTHORIZATION_ERROR: The api_key is disabled, the call limit is exceeded, there is no permission to call this API, or no permission to call it in the current manner. values:API_KEY_BE_DISCONTINUED: the api_key is disabled.IP_NOT_ALLOWED: IP not allowed (reserved design).LIMIT_REACHED: this api_key has reached the call limit for the current API (only for test keys).MORE_RETRY_TIMES: the comparison retry limit is reached.DENIED: no permission to call the current API.EXPIRED_SIGN: the signature has expired.INVALID_SIGN: invalid signature.Reserve handling for other possible error codes.
403 CONCURRENCY_LIMIT_EXCEEDED The concurrency limit is exceeded.
404 API_NOT_FOUND The API does not exist.
413 Request Entity Too Large The request size sent by the client exceeds the 10 MB limit. This error is returned in plain text, not JSON.
500 INTERNAL_ERROR Internal server error. If this error occurs, send the request again. If it persists, contact FinAuth customer service or business support.

# Billing Status Codes

result_code result_message Meaning Billable
1000 SUCCESS Comparison verification succeeded. Yes
2000 PASS_LIVING_NOT_THE_SAME After verification, the photo to be compared is not the same person as at least one of the other photos. Yes