# Face Compare API

Note

Face Compare API will be deprecated in the release of V2.0, please check the more accurate Face Match API.

Face Compare API as the name suggests compares faces in two images and determines if they belong to the same person.

Face Compare is an alternative to Face Match - both of the technologies are used for Face Authentication. The only difference is that Face Match provides a response as Absolute Distance value between 0 to 1 and Face Compare API response is of a more Human Readable % (percentage) form.

# How it works?

The Face Compare API accepts two Images as input and each of the Images should contain only a single face.

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 Compare 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 Compare API is used for applications where you need to determine if two faces belong to the same person or not. The API accepts two faces as inputs (using the tag img_1 & img_2) and provides match confidence as output.

# Image Guidelines Recommendation

In general, as the Face Compare 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, since it could 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/compare_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 An image file supported files jpeg, png or Base64 or Image URL
img_2 An image file supported files jpeg, png or Base64 or Image URL

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.

# 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": {
        "confidence": "0.72201766679"
    }

# Response Definition Explained

The following are the output definitinos of the Face Compare API

Attribute Name Definition Value Range
Confidence Response in % form (eg. o.5 corresponds to 50%) 0 to 1
<0.6 => Not a Match , >0.6 => Match

# Video Demo of Web-Trial

# Sample Codes

cURL Image File

# you can get the app_id in user dashboard

curl --request POST \
  --url 'http://facexapi.com/compare_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/compare_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/compare_faces?face_det=1"; // face compare 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/compare_faces?face_det=1";// face compare 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/compare_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/compare_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/compare_faces?face_det=1" # face compare 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/compare_faces" # face compare 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/compare_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/compare_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))

}
Last Updated: 5/12/2020, 4:35:31 PM