# Face Vector API

Face Vector API maps the detected faces on a 128-point vector scale which can be used for performing facial recognition

# Using FaceVector for Facial recognition

To perform Recognition using FaceVector API

  • The Face vectors provided by the API have to be stored as a template for the person in a database.
  • When Face recognition has to be done, the new face is run through Face Vector API to obtain the new Face Template
  • The Euclidean distance between the two Face Templates is to be calculated. Result: When the Euclidean distance is less than 0.5 it is considered a match and both images belong to the same person.

# What can I use this Vector for ? Explained

Vectors are templates that you could save instead of the image in itself, it can be thought of an encrypted Image Template, it is nearly impossible to re-create the actual image from the Vector. But this template would be enough to perform Facial Identification.

Learn How to do a Facial Recognition to find the closest match from your database of Image Vectors

# How it works?

The Face Vector API accepts only a single image as input and the Image should ideally contain only a single face for best results.

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 Vector 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 Vector API is the base API used in all of the FaceX facial recognition applications. The basic function of the FaceVector API is to convert the provided face into a 128-Vector Matrix template which can be used for recognition.

# Image Guidelines Recommendation

In general, as the Face Vector 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/get_face_vec

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 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.

# Additional Parameter 1 Optional

Key Type Description
bboxes String bboxes for the face in img

Example

If the bounding boxes for img is : 130,189,240,300, your Request URL would look like

http://www.facexapi.com/get_face_vec?bboxes=130,180,240,300

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:"120,150,200,250"

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

# Additional Parameter 2 Optional

FaceX offers an additional Request Parameter with which you could collect a vector only if the images match the minimum Image Guidelines stated above.

Key Type Description
quality boolean 1 or 0

Example

If the quality flag in your header is set to 1, your Request URL would look like

http://www.facexapi.com/get_face_vec?quality=1

Three attributes are analysed by this API before providing a response:

  • Face Size
  • Lighting
  • Pose

The API responds with an error if any of the condition are not met.

Response Errors provided

Attribute Error Required Threshold
Image Size Face too Small The size of the Face provided to the Vector API should be minimum 60×60
Lighting Low Illumination Illumination of the image should be a minimum of 70
Pose Incorrect Pose The threshold for FaceAPI is 50 yaw

# Response Sample

The output provided by the FaceVector API is a 128-Vector Matrix which can be used as the face template for the face provided

See a sample response
 	"status": "ok",
    "code": "1000",
    "success": true,
    "message": "Fetched vector data.",
    "data": {
        "vector": [
            -0.10755891352891922,
            0.023342471569776535,
            -0.040798187255859375,
            -0.05398240685462952,
            -0.1586793214082718,
            0.037553660571575165,
            -0.0031917672604322433,
            -0.09310519695281982,
            0.10062528401613235,
            -0.04365912452340126,
            0.29004979133605957,
            0.034670621156692505,
            -0.24202501773834229,
            -0.09383172541856766,
            -0.014479083940386772,
            0.1104440838098526,
            -0.184284970164299,
            -0.07144159823656082,
            -0.05719197541475296,
            0.012539735063910484,
            0.031796641647815704,
            0.04901798814535141,
            0.027894478291273117,
            0.12718209624290466,
            -0.07219891250133514,
            -0.3904838562011719,
            -0.016163257881999016,
            -0.11717362701892853,
            0.0713876485824585,
            -0.14125311374664307,
            -0.023526130244135857,
            0.06685655564069748,
            -0.13618619740009308,
            -0.056744590401649475,
            0.012897368520498276,
            0.07639331370592117,
            -0.01843799091875553,
            -0.0684841126203537,
            0.15621361136436462,
            0.01983575150370598,
            -0.1822613626718521,
            0.055347323417663574,
            0.02209659293293953,
            0.29141244292259216,
            0.18907180428504944,
            0.025656800717115402,
            0.054874565452337265,
            -0.12605944275856018,
            0.13173161447048187,
            -0.2922557592391968,
            0.043907929211854935,
            0.14100797474384308,
            0.08359767496585846,
            0.008628152310848236,
            -0.01711672730743885,
            -0.12023848295211792,
            0.00823773443698883,
            0.11360819637775421,
            -0.22895076870918274,
            0.08459965139627457,
            0.09580466151237488,
            0.01135856844484806,
            0.005259900353848934,
            -0.0658416897058487,
            0.16549402475357056,
            0.08643916249275208,
            -0.13728687167167664,
            -0.10083258897066116,
            0.07119660079479218,
            -0.19645465910434723,
            -0.11978771537542343,
            0.008368134498596191,
            -0.1343500018119812,
            -0.24177630245685577,
            -0.24675415456295013,
            0.05565771460533142,
            0.33436837792396545,
            0.20437367260456085,
            -0.19437113404273987,
            0.000054001808166503906,
            -0.12213395535945892,
            0.010422419756650925,
            0.0967920571565628,
            0.05234392359852791,
            0.002123866230249405,
            -0.11699287593364716,
            -0.12567518651485443,
            0.026080913841724396,
            0.18500323593616486,
            0.004016300663352013,
            0.03161687031388283,
            0.2920586168766022,
            0.05549748241901398,
            0.0026979241520166397,
            0.054879941046237946,
            0.1544187068939209,
            -0.1262151300907135,
            0.051863718777894974,
            -0.10847119241952896,
            0.0033754557371139526,
            0.020403888076543808,
            -0.06793229281902313,
            0.08950775861740112,
            0.10104835033416748,
            -0.21474668383598328,
            0.2293572872877121,
            -0.047598645091056824,
            0.027161655947566032,
            0.1429743617773056,
            -0.0365825816988945,
            -0.062250278890132904,
            -0.05306026712059975,
            0.13243430852890015,
            -0.2177596092224121,
            0.23045741021633148,
            0.19510893523693085,
            0.11666344106197357,
            0.1563301533460617,
            0.05955293029546738,
            0.06330647319555283,
            -0.03221378102898598,
            -0.049815259873867035,
            -0.18635915219783783,
            -0.05796624347567558,
            0.033074721693992615,
            -0.06805479526519775,
            -0.006529608741402626,
            -0.00988270528614521
        ]
	}
	```

ℹ️ If you do not receive the above response, please refer to our Error Glossary to find out why.


# Video Demo of Web-Trial

# Sample Codes

cURL Image File

# you can get the user_id in user dashboard

curl --request POST \
  --url 'http://facexapi.com/get_face_vec' \
  --header 'content-type: multipart/form-data' \
  --header 'user_id: your_user_id' \
--form [email protected]_image_path 
cURL Base64 Image or URL

# you can get the user id in user dashboard
curl --request POST \
  --url 'http://facexapi.com/get_face_vec' \
  --header "Content-Type: application/json" \
  --header 'user_id: your user_id' \
  --data '{
    "img":"https://cdn.dnaindia.com/sites/default/files/styles/full/public/2018/03/08/658858-577200-katrina-kaif-052217.jpg"
}'
ruby Image File
require 'uri'
require 'net/http'

url = URI("https://www.facexapi.com/get_face_vec")
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\"; filename=\"your_file_name\"\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/get_face_vec")
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\": \"image_url/base64\"\n}"
response = http.request(request)
puts response.read_body
python Image File
import requests
# you can get the user_id in the user dashboard
USER_ID = "your user_id"
#-------------------------

IMAGE_PATH = "/home/atul/Downloads/kat.jpeg" # add image path from local system
API_URL = "http://facexapi.com/get_face_vec?face_det=1" # feature vector url
files = {'img': open(IMAGE_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"
#-------------------------

IMAGE_URL = "https://cdn.dnaindia.com/sites/default/files/styles/full/public/2018/03/08/658858-577200-katrina-kaif-052217.jpg" # add image url
API_URL = "http://facexapi.com/get_face_vec" # feature vector url
payload = {"img": IMAGE_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/get_face_vec"
	payload := strings.NewReader("------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"img\"; 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/get_face_vec"
	payload := strings.NewReader("{\n\t\"img\": \"image_url_orbase64\"\n\t\n}")
	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("user_id", "your_user_id")
	req.Header.Add("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)
	fmt.Println(res)
	fmt.Println(string(body))

}

# Additional Reading

ℹ️ If you do not receive the above response, please refer to our Error Glossary to find out why.

  1. How to do a 1:n Image Search with Vectors
Last Updated: 5/12/2020, 4:35:31 PM