Face Recognition

Names the people in a photograph from a face database you keep with us: register a face under a name, then recognise it in later images, one face or every face at once.

POST/v3/store/ekyc/face-recognition/single

+7 endpoints

Try it

• Price0.3 ICper request
• Measured84.1%
• Served54.7Kcalls

• v1.3.0
• Active
• Benchmark paper (PDF)

Input

file

photo.jpg

company

iApp

OutputPOST /v3/store/ekyc/face-recognition/single

message

successfully performed

company

YOUR_COMPANY

name

John Doe

recognition_score

0.8523

detection_score

0.9998

bbox

xmin: 154.39 ymin: 155.49 xmax: 255.45 ymax: 282.88

process_time

0.4776

Every field, under ResponseOther endpoints: /add, /check, /export, /facecrop, /import, /multi, /remove see Request

Request

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-recognition/single \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "company=iApp"

Response

200OK. The fields are explained under Response.

{
  "message": "successfully performed",
  "company": "YOUR_COMPANY",
  "name": "John Doe",
  "recognition_score": 0.8523,
  "detection_score": 0.9998,
  "bbox": {
    "xmin": 154.39,
    "ymin": 155.49,
    "xmax": 255.45,
    "ymax": 282.88
  },
  "process_time": 0.4776
}

Request

multipart/form-data. Every call names the database in company, and calls that change it also take its password; the demo database is iApp, password iApp.

Headers

apikeystringrequired

Your API key, created under API Keys in the control panel.

Body

filefilerequired

The photograph. JPEG or PNG, up to 2 MB, at least 600 × 400 px; a face at least 112 × 112 px.

companystringrequired

Your company identifier, which names your face database.

Endpoint	Does	Price
/v3/store/ekyc/face-recognition/single	Recognises the most prominent face	0.3 IC per request
/v3/store/ekyc/face-recognition/multi	Recognises every face, as faces[]	0.3 IC per request
/v3/store/ekyc/face-recognition/add	Registers a face under name	0.1 IC per request
/v3/store/ekyc/face-recognition/remove	Removes a name, or one face_id	Free
/v3/store/ekyc/face-recognition/check	Counts the database; save_file=1 returns it as CSV	0.3 IC per request
/v3/store/ekyc/face-recognition/import, /export	Moves face features in and out as CSV or Excel (type_file)	Free

The database calls

Endpoint	Fields	Returns
/add	file, company, name, password	face_id, name, and face, the registered face as a base64 PNG
/remove	company, name, password, and face_id to remove one of several	removed, the removed face_id list, and face_num, the faces left in the database
/check	company, password, save_file	feature_count (faces), name_count (people), and name with the faces per person
/import	file (CSV with name, face_id, feature_vector), company, password	imported_count, failed_count
/export	company, password, type_file = csv or excel	The file

Register 3 to 5 sharp, frontal, well-lit photographs per person, with some variation in expression. Every database uses thresholds of detection 0.95, comparison 0.50 and recognition 0.50: a search names the best-matching person only when recognition_score is above 0.50, and otherwise returns unknown. For a stricter decision, accept a name only above a higher score of your own; Measured shows what each value does. Everyone who tries the demo shares the iApp database, so register only test photographs there.

Response

/single returns the best match at the top level, as in the panel; /multi returns the same fields for each face inside faces.

namestring

The registered name, or unknown when no face in the database reaches the recognition threshold

recognition_scorenumber

Confidence in the name, 0 to 1

detection_scorebbox

Confidence in the face and its xmin, ymin, xmax, ymax

messagecompanyprocess_time

successfully performed; the database; seconds

Status codes

Code	Meaning
413	The file is over 2 MB
415	Unsupported file format
420, 421, 422	A required field is missing, invalid, or malformed; parameter names it
423	No face found in the image
424	Several faces found; use /multi
427	Not allowed on the demo database
428, 429	Export or import failed

Details

Measured

On the public LFW benchmark, with one registered photograph per person and 1,680 people in the database, we searched with 2,581 other photographs of registered people and 1,500 photographs of people never registered. Each search named the right person, named a wrong person, or returned unknown:

Accepted when recognition_score is above	Right person	Wrong registered person	Unregistered person named
0.50 (default)	84.1%	0.31%	0.13%
0.55	74.2%	0.27%	0.13%
0.60	61.3%	0.15%	0.13%
0.70	29.1%	0.04%	0.07%
0.85	2.2%	0.04%	0.07%

The best match was the right person in 97.6% of searches; at the default, most of the others return unknown because one uncontrolled photograph of a person often scores below 0.50. These figures are for one photograph per person; registering several was not measured. Through the API, a search took 0.59 s median (90th percentile 0.89 s) with 20 people registered; search time grows with the number of registered faces. Method and errors: the benchmark (PDF).

Limits

• Best when the face fills 15% or more of the frame.
• Frontal within 15°, both eyes visible, no sunglasses or mask; profile views are not recommended.
• Lighting, sharpness, expression, age and accessories lower the score.
• A large database recognises more slowly; export a backup and remove stale entries.

Data handling

Images are not kept after processing. Only the face features computed from each registered photograph are stored, in your database, and its password only as a salted hash. Biometric data needs the subject's explicit consent under GDPR and PDPA, and the right to erasure applies: /remove deletes a person's face features from the service at once, and the disaster-recovery backups that may still hold them are replaced within 7 days.