TinyFaceMatch is an open-source, AI powered face verification model for comparing two aligned face images and returning a match decision with similarity scores.

The recommended production model is:

tinyfacematch-128-pretrained.onnx

Default threshold:

0.2856

License: MIT. No separate commercial license needs to be acquired to use this repository.

Input contract:

RGB image -> 112x112 -> (pixel - 127.5) / 128.0 -> NCHW float32

Output contract:

L2-normalized 128-D embedding

Install directly from GitHub:

pip install git+https://github.com/yuvrajraina/tinyfacematch.git

Or install from a local clone:

git clone https://github.com/yuvrajraina/tinyfacematch.git
cd tinyfacematch
pip install -e ".[onnx]"

The Django backend is the single Render service for both products:

GET  /api/model/
POST /api/verify/
GET  /api/liveness/model/
POST /api/liveness/predict/

Keep the TinyFaceMatch and TinyLiveness frontends deployed as separate static sites. Point both frontends at the same Render backend, using /api/verify/ for face matching and /api/liveness/predict/ for liveness.

The backend installs TinyLiveness from its separate release repo/tag, so the TinyLiveness source folder should stay out of this repo.

curl -L -o tinyfacematch-128-pretrained.onnx \
  https://github.com/yuvrajraina/tinyfacematch/releases/latest/download/tinyfacematch-128-pretrained.onnx

Optional smaller INT8 model:

curl -L -o tinyfacematch-128-pretrained-int8.onnx \
  https://github.com/yuvrajraina/tinyfacematch/releases/latest/download/tinyfacematch-128-pretrained-int8.onnx

Recommended SHA-256 for the FP32 model:

6d8588c1dc1f91fab930be355d33d4b6be0b74d70c46ae0f9c65d89be2865aa4

from tinyfacematch import OnnxFaceEmbedder

embedder = OnnxFaceEmbedder("tinyfacematch-128-pretrained.onnx")

result = embedder.verify_images(
    left_rgb,
    right_rgb,
    threshold=0.2856,
)

print(result.is_match)
print(result.similarity)
print(result.distance)

left_rgb and right_rgb should be RGB NumPy arrays. For best accuracy in production, run face detection and alignment before calling the embedder.

If you already have normalized face crops or want to store/search embeddings:

from tinyfacematch import OnnxFaceEmbedder, verify_embeddings

embedder = OnnxFaceEmbedder("tinyfacematch-128-pretrained.onnx")

left_embedding = embedder.embed_image(left_rgb)
right_embedding = embedder.embed_image(right_rgb)

result = verify_embeddings(left_embedding, right_embedding, threshold=0.2856)

• Detect and align faces before verification.
• Keep raw face images out of logs.
• Treat embeddings as sensitive biometric-derived data.
• Version the model file and threshold together.
• Monitor false accepts, false rejects, latency, and no-face rates.
• Provide user consent, deletion, and fallback flows.
• Do not use face verification as the only signal for high-impact decisions.

Always review upstream model and dataset licenses before using third-party weights commercially.