# Face Match API

Face Match API compares two faces and determines if they belong to the same person, it is also commonly referred to as the Face Authentication API as it serves the purpose of Authenticating users.

# How it works ?

Face Match API is an extension of the FaceVector API. The API responds back with a Match distance between the two images sent to the server. Depending on this Euclidean distance, the API responds if the images are a match or not.

If the Euclidean Distance of the images is less than the threshold of 0.5, it can be concluded that the faces are a MATCH and naturally above 0.5 it can be considered NOT A MATCH.

Note on Input Constraints

If there is more than one face in each of the image submitted in the request, the API will auto-detect and provide the response for the first face it detects in each image.

To avoid this, we recommend the use of bbox parameter in your request, to specify which image needs to be analysed.

# How to Subscribe ?

To start using the Face Match API, you need to sign up and subscribe to one of the FaceAPI plans View payment plans here. Learn more about signing up to the FaceAPI plans in our article “Getting Started with FaceX APIs“.

# How to send a POST Request?

Face Match API is used for applications where you need to determine if two faces belong to the same person. The API accepts two faces as inputs (using the tag img_1 & img_2) and provides the result as a response to the request.

# Image Guidelines Recommendation

In general, as the Face Match API does not filter the image to support various applications, any image would be accepted by the API. However, for best results there are a few factors to keep in mind. Please refer to the article “Image Quality for Facial Recognition” for best practices.

We recommend an image resolution no higher than 1024p resolution as anything higher would slow down the response received. Supported image formats are JPEG/PNG/JPG format.

“Read more about the recommended Image Quality“

# Request

Our Global Request Endpoint : http://www.facexapi.com/match_faces

Key Description Type
user_id Your valid User ID (as shown in your user portal when you log in) String
content-type multipart/form-data (if using image file)
application/json (if using Base64/URL)

# Body

Key Description Type
img_1 File (or) String An image file, base64 or URL of the first person
img_2 File (or) String An image file, base64 or URL of the second person

Please Note:

Certain Image URLs may not be accessible to the server (if not on HTTPS) or may take too long to load and therefore it is recommended to upload it as File Input or Base64 from above.

Kindly ensure that the file format for img_1 & img_2 are both the same

# Params Optional

Key Type Description
bboxes_1 String bboxes for the face in img_1
bboxes_2 String bboxes for the face in img_2

Example

If the bounding boxes for img_1 is : 1035,239,1216 and img_2 is 822,492,968,666, your Request URL would look like

http://www.facexapi.com/match_faces?bboxes_1=1035,239,1216,450&bboxes_2=822,492,968,666

You will need to use the Params Header only if you want to selectively get the results from a photo with multiple faces.

If bounding box coordinates are available set values for key 'bboxes' in format x1,y1,x2,y2. ex:"130,180,240,300"

Learn more about the bboxes article in this in-depth article


# Response Sample

See a sample response
    "status": "ok",
    "code": "1000",
    "success": true,
    "message": "Fetched confidence value.",
    "data": {
        "score": "0.2586751709411996",
        "status": "match"
    }

# Response Definition Explained

The following are the output definitinos of the Face Match API

Attribute Name Definition Value Range
Status Response in Human Readable String Match (or) Not a Match
Score 0 to 0.9 <0.5 => Match , >0.5 => Not a Match

# Sample Codes

cURL Image File
# you can get the app_id in user dashboard

curl --request POST \
  --url 'http://facexapi.com/match_faces' \
  --header 'content-type: multipart/form-data' \
  --header 'user_id: your user_id' \
--form [email protected]_first_image_path \
--form [email protected]_second_image_path
cURL Base64 Image or URL
# you can get the app_id in user dashboard
curl --request POST \
  --url 'http://facexapi.com/match_faces' \
  --header "Content-Type: application/json" \
  --header 'user_id: your user_id' \
  --data '{
	"img_1":"https://cdn.dnaindia.com/sites/default/files/styles/full/public/2018/03/08/658858-577200-katrina-kaif-052217.jpg",
  "img_2":"https://cdn.dnaindia.com/sites/default/files/styles/full/public/2018/03/08/658858-577200-katrina-kaif-052217.jpg"
}'
PHP Image File
<?php
// you can get the app_id in user dashboard
$APP_ID = "your_app_id";
//----------------------

// add image path from local system
$IMAGE1_PATH ="first_image_path";
$IMAGE2_PATH ="second_image_path";
//---------------

function makecUrlFile($file){
  $mime = mime_content_type($file);
  $info = pathinfo($file);
  $name = $info['basename'];
  $output = new CURLFile($file, $mime, $name);
  return $output;
}


$imageObject1 = makecUrlFile($IMAGE1_PATH);
$imageObject2 = makecUrlFile($IMAGE2_PATH);
$request = curl_init();
$queryUrl = "http://facexapi.com/match_faces?face_det=1"; // face match url
$imageObject =  array("img_1" => $imageObject1, "img_2" => $imageObject2);
curl_setopt($request, CURLOPT_URL, $queryUrl);
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array(
    "content-type: multipart/form-data",
    "user_id:" . $APP_ID,

)
    );
curl_setopt($request,CURLOPT_POSTFIELDS,$imageObject);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($request);  // curl response
    echo $response;
    curl_close($request);
?>
PHP Base64 Image or URL
<?php
// you can get the app_id in user dashboard
$APP_ID = "your_app_id";

//-----------------------

// add image url
$IMAGE1_URL = "first_image_url";
$IMAGE2_URL = "second_image_url";
//--------------------------

$queryUrl = "http://facexapi.com/match_faces?face_det=1";// face match url

$imageObject =  array("img_1" => $IMAGE1_URL , "img_2" => $IMAGE2_URL);
$request = curl_init();
curl_setopt($request, CURLOPT_URL, $queryUrl);
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request,CURLOPT_POSTFIELDS,$imageObject);
curl_setopt($request, CURLOPT_HTTPHEADER, array(
    "Content-type: application/json",
    "user_id:" . $APP_ID,
  
)
    );
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($request); // curl response
echo $response;
curl_close($request);
?>
ruby Image File
require 'uri'
require 'net/http'

url = URI("https://www.facexapi.com/match_faces")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'multipart/form-data'
request["user_id"] = 'your_user_id'
request.body = "------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"img_1\"; filename=\"image_file\"\r\nContent-Type: image/jpeg\r\n\r\n\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"img_2\"; filename=\"image file\"\r\nContent-Type: image/jpeg\r\n\r\n\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW--"
response = http.request(request)
puts response.read_body
ruby Base64 Image or URL

require 'uri'
require 'net/http'

url = URI("https://www.facexapi.com/match_faces")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["user_id"] = 'your_user_id'
request.body = "{\n\t\"img_1\":\"image_url/base\",\n\t\"img_2\":\"image_url/base\"\n}"
response = http.request(request)
puts response.read_body
python Image File
import requests
# you can get the user_id in user dashboard
USER_ID = "your_user_id"
#--------------------------------

# add image path from local system
IMAGE1_PATH = "/home/atul/Downloads/kat.jpeg"
IMAGE2_PATH = "/home/atul/Downloads/kat.jpeg"
#--------------------------------
API_URL = "http://facexapi.com/match_faces?face_det=1" # face match url
files = {'img_1': open(IMAGE1_PATH, 'rb'),'img_2': open(IMAGE2_PATH, 'rb')}
headers = {"user_id": USER_ID }
r = requests.post(API_URL,headers = headers,files = files) # comment this line to use url image
print (r.text) # printing response
python Base64 Image or URL
import requests
import json
# you can get the user_id in user dashboard
USER_ID = "your user_id"
#--------------------------------


# add image url
IMAGE1_URL = "https://cdn.dnaindia.com/sites/default/files/styles/full/public/2018/03/08/658858-577200-katrina-kaif-052217.jpg"
IMAGE2_URL = "https://cdn.somethinghaute.com/wp-content/uploads/2018/07/katrina-kaif.jpg"
#---------------------------------

API_URL = "http://facexapi.com/match_faces" # face match url
payload = {"img_1": IMAGE1_URL,"img_2": IMAGE2_URL}
headers = {"user_id": USER_ID ,"Content-Type":"application/json"}
r = requests.post(url = API_URL,headers = headers,data = json.dumps(payload)) # uncomment this line to use url image
print (r.text) # printing response
GO Image File
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://www.facexapi.com/match_faces"
	payload := strings.NewReader("------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"img_1\"; filename=\"image_file\"\r\nContent-Type: image/jpeg\r\n\r\n\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"img_2\"; filename=\"image_file\"\r\nContent-Type: image/jpeg\r\n\r\n\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW--")
	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("user_id", "your_user_id")
	req.Header.Add("Content-Type", "multipart/form-data")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)
	fmt.Println(res)
	fmt.Println(string(body))

}
GO Base64 Image or URL
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://www.facexapi.com/match_faces"
	payload := strings.NewReader("{\n\t\"img_1\":\"image_url_or_base64\",\n\t\"img_2\":\"image_url_or_base64\"\n}")
	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("user_id", "your_user_id")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)
	fmt.Println(res)
	fmt.Println(string(body))

}

# Additional Reading

  1. How to do a 1:1 Image Verification with Face Match API
Last Updated: 5/12/2020, 4:35:31 PM