👥🔍 Face Verification 🆕

👤👤🔍 ระบบยืนยันตัวตนด้วยใบหน้า

Welcome to Face Verification API Version 2, an AI product developed by iApp Technology Co., Ltd. Our API is designed to verify and compare faces between two images with high accuracy and speed. The API provides similarity scores to help determine if two faces belong to the same person.

Try Demo!

Image Main Example Images (Click to try)

Image Compare Example Images (Click to try)

API Key

Demo key is limited to 10 requests per day per IP
Click here to get your API key

Endpoint URL

cURL Command

Upload Image Main

Upload Image Compare

Getting Started

1. Prerequisites

   • An API key from iApp Technology
   • Two image files containing faces to compare
   • Supported formats: JPG, JPEG, PNG, HEIC, and HEIF
   • Maximum file size: 2MB per image
   • Minimum image size: 600px x 400px for a person and multiple people

2. Quick Start

   • Fast processing time
   • High accuracy face verification
   • Support for multiple file formats
   • Flexible scoring options

3. Key Features

   • Face-to-face comparison
   • Similarity scoring
   • Company-specific thresholds
   • Custom minimum score settings
   • Face detection confidence scores

4. Security & Compliance

   • GDPR and PDPA compliant
   • No image data retention
   • Secure API endpoints

How to get API Key?

Please visit API Portal to view your existing API key or request a new one.

Understanding Similarity Scores

The similarity score ranges from 0 to 2822, which is derived from face template matching from 166 points on face, for each point ranging from 0-17 similarity scope range which calculated from the distance, angle, and special characteristics between 17 surround points. More score has higher chance to be the face of a same person.

The standard thresholds for 99.50% precision is 36. Thus, if the score is less than 36, it will consider to be different person, otherwise, if the score is greater than 36 it should be considered as the same person face.

The higher threshold of 99.95% precision is 48.

note

The actual threshold should be determined based on your specific use case and security requirements.

Example

Face Verification API Request

Image Preview

curl --location --request POST 'https://api.iapp.co.th/face-verification/v2/face_compare' \
    --header 'apikey: YOUR_API_KEY' \
    --form 'file1=@"{Your Image File Path 1}"' \
    --form 'file2=@"{Your Image File Path 2}"'

Face Verification API Response:

{
    "duration": 2.1263949871063232,
    "matched": true,
    "message": "successfully performed",
    "score": 38.0,
    "threshold": 37
}

Features & Capabilities

Core Features

• Face detection and comparison
• Support for JPG, JPEG, PNG, HEIC, and HEIF formats
• Minimum image size: 600px width x 400px height for a person and multiple people
• Maximum file size: 2MB
• Customizable detection and comparison scores
• REST API interface
• Privacy-focused: processes numeric features without storing images

Supported Operations

• Face comparison between two images
• Company-specific score configuration
• Custom minimum score thresholds

API Reference

Endpoint

POST https://api.iapp.co.th/face-verification/v2/face_compare

Request Headers

Name	Type	Required	Description
apikey	string	Yes	Your API key

Request Body (multipart/form-data)

Parameter	Type	Required	Description
file1	File	Yes	First image for comparison
file2	File	Yes	Second image for comparison
threshold	Number	No	Threshold score for face matching decision. Default value is 36. To achieve very low False Acceptance Rate (FAR), you can set it to 48.

Error Codes

Common Errors

Code	Message	Description
404	No route matched	Invalid API endpoint
405	Method not allowed	Invalid HTTP method
413	File too large	Image exceeds 2MB limit
415	Invalid extension	Unsupported file format

Processing Errors

Code	Message	Description
420	Parameter missing	Required parameter not provided
423	Face not found	No face detected in image
440	No file attached	Image file not included
441	Too many images	Too many image files provided
442	Unsupported format	Invalid image format

Server Errors

Code	Message	Description
560	Server busy	Server queue full
561	Processing timeout	Operation took too long
562	Request timeout	Queue wait too long

Code Examples

Python

import requests

url = "https://api.iapp.co.th/face-verification/v2/face_compare"

# Use default score
payload={}

files=[
  ('file1',('{Your Image File Name 1}',open('{Your Image File Path 1}','rb'),'application/octet-stream')),
  ('file2',('{Your Image File Name 2}',open('{Your Image File Path 2}','rb'),'application/octet-stream'))
]
headers = {
  'apikey': '{Your API Key}'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

Javascript

const axios = require("axios")
const FormData = require("form-data")
const fs = require("fs")
let data = new FormData()
data.append("file1", fs.createReadStream("/Users/iapp/Downloads/facever_test1 (3).png"))
data.append("file2", fs.createReadStream("/Users/iapp/Downloads/facever_test2 (3).png"))

let config = {
    method: "post",
    maxBodyLength: Infinity,
    url: "https://api.iapp.co.th/face-verification/v2/face_compare",
    headers: {
        apikey: "YOUR_API_KEY",
        ...data.getHeaders(),
    },
    data: data,
}

axios
    .request(config)
    .then((response) => {
        console.log(JSON.stringify(response.data))
    })
    .catch((error) => {
        console.log(error)
    })

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.iapp.co.th/face-verification/v2/face_compare',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('file1'=> new CURLFILE('{Your Image File Name 1}'),'file2'=> new CURLFILE('{Your Image File Name 2}')),
  CURLOPT_HTTPHEADER => array(
    'apikey: {Your API Key}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Swift

let parameters = [
  [
    "key": "file1",
    "src": "{Your Image File Name 1}",
    "type": "file"
  ],
  [
    "key": "file2",
    "src": "{Your Image File Name 2}",
    "type": "file"
  ]] as [[String: Any]]

let boundary = "Boundary-\(UUID().uuidString)"
var body = Data()
var error: Error? = nil
for param in parameters {
  if param["disabled"] != nil { continue }
  let paramName = param["key"]!
  body += Data("--\(boundary)\r\n".utf8)
  body += Data("Content-Disposition:form-data; name=\"\(paramName)\"".utf8)
  if param["contentType"] != nil {
    body += Data("\r\nContent-Type: \(param["contentType"] as! String)".utf8)
  }
  let paramType = param["type"] as! String
  if paramType == "text" {
    let paramValue = param["value"] as! String
    body += Data("\r\n\r\n\(paramValue)\r\n".utf8)
  } else {
    let paramSrc = param["src"] as! String
    let fileURL = URL(fileURLWithPath: paramSrc)
    if let fileContent = try? Data(contentsOf: fileURL) {
      body += Data("; filename=\"\(paramSrc)\"\r\n".utf8)
      body += Data("Content-Type: \"content-type header\"\r\n".utf8)
      body += Data("\r\n".utf8)
      body += fileContent
      body += Data("\r\n".utf8)
    }
  }
}
body += Data("--\(boundary)--\r\n".utf8);
let postData = body


var request = URLRequest(url: URL(string: "https://api.iapp.co.th/face-verification/v2/face_compare")!,timeoutInterval: Double.infinity)
request.addValue("{YOUR API KEY}", forHTTPHeaderField: "apikey")
request.addValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Kotlin

val client = OkHttpClient()
val mediaType = "text/plain".toMediaType()
val body = MultipartBody.Builder().setType(MultipartBody.FORM)
  .addFormDataPart("file1","{Your Image File Name 1}",
    File("{Your Image File Path 1}").asRequestBody("application/octet-stream".toMediaType()))
  .addFormDataPart("file2","{Your Image File Name 1}",
    File("{Your Image File Path 1}").asRequestBody("application/octet-stream".toMediaType()))
  .build()
val request = Request.Builder()
  .url("https://api.iapp.co.th/face-verification/v2/face_compare")
  .post(body)
  .addHeader("apikey", "{YOUR API KEY}")
  .build()
val response = client.newCall(request).execute()

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
  .addFormDataPart("file1","{Your Image File Name 1}",
    RequestBody.create(MediaType.parse("application/octet-stream"),
    new File("{Your Image File Path 1}")))
  .addFormDataPart("file2","{Your Image File Name 2}",
    RequestBody.create(MediaType.parse("application/octet-stream"),
    new File("{Your Image File Path 2}")))
  .build();
Request request = new Request.Builder()
  .url("https://api.iapp.co.th/face-verification/v2/face_compare")
  .method("POST", body)
  .addHeader("apikey", "{YOUR API KEY}")
  .build();
Response response = client.newCall(request).execute();

Dart

var headers = {
  'apikey': '{YOUR API KEY}'
};
var request = http.MultipartRequest('POST', Uri.parse('https://api.iapp.co.th/face-verification/v2/face_compare'));
request.files.add(await http.MultipartFile.fromPath('file1', '{Your Image File Path 1}'));
request.files.add(await http.MultipartFile.fromPath('file2', '{Your Image File Path 2}'));
request.headers.addAll(headers);

http.StreamedResponse response = await request.send();

if (response.statusCode == 200) {
  print(await response.stream.bytesToString());
}
else {
  print(response.reasonPhrase);
}

Limitations and Best Practices

Limitations

• Maximum file size: 2MB
• Minimum image dimensions: 600x400 pixels
• Supported formats: JPG, JPEG, PNG, HEIC and HEIF file and BASE64 format
• One face per image for comparison and multiple people

Best Practices

• Use clear, well-lit face images
• Ensure face is clearly visible and unobstructed
• Submit images meeting minimum size requirements
• Stay within file size limits
• Use appropriate file formats

Accuracy & Performance

• High accuracy face detection
• Fast processing time
• Configurable confidence thresholds
• Factors affecting accuracy:
  • Image quality
  • Face visibility
  • Lighting conditions
  • Face angle/pose

Pricing

AI API Service Name	Endpoint	IC Per Request	On-Premise
Face Verification (Comparison)	iapp_face_verification_v1	0.2 IC/Request	Contact
	iapp_face_verification_v2	0.3 IC/Request