POST/api/v1/face/search

Gallery-Based Face Search API

Upload a probe face and a gallery of images. Receive ranked matches with filenames, distances, and per-model scores — perfect for forensics, attendance, and media tagging.

Get started free View API docs
POST /api/v1/face/search

REQUEST

█
200 OK
{
  "matches": [
    { "filename": "person1.jpg", "distance": 0.24, "matched": true },
    { "filename": "person2.jpg", "distance": 0.61, "matched": false }
  ],
  "query_processed": true
}

Key Features

Everything you need from a production-ready Face Search API.

Multi-Model Ranking

Three models rank gallery images independently then results are fused for accuracy.

Filename Preservation

Matched gallery images are returned with their original filenames for easy lookup.

Large Gallery Support

Submit up to dozens of gallery images per request. Results ranked by confidence.

Distance Breakdown

Per-model distances returned alongside the fused result for full transparency.

How it works

Integrate in minutes with our developer-friendly REST API.

01

Upload probe + gallery

POST query (the face to find) and one or more gallery images in a single request.

02

Parallel search

Three models compute distances between the probe and every gallery image simultaneously.

03

Ranked results

Receive gallery images ranked by match confidence, closest first.

Data Output

Fields You Can Extract

All data returned as structured JSON — map directly to your database schema.

matches[].filename
matches[].distance
matches[].matched
query_processed
response.json
{
  "matches": [
    { "filename": "person1.jpg", "distance": 0.24, "matched": true },
    { "filename": "person2.jpg", "distance": 0.61, "matched": false }
  ],
  "query_processed": true
}

Mobile SDK

NO API KEY

Face Capture SDK

Capture a face image natively in your app and pass it to this endpoint. No API key needed for the capture itself.

Add to build.gradle.kts — Kotlin 2.0+:

Kotlin
dependencies {
    implementation("com.codelyticalhub:face-capture:1.0.0")
}
// settings.gradle.kts
repositories { mavenCentral() }

Manifest permission (runtime request handled by the SDK):

XML
<uses-permission android:name="android.permission.CAMERA" />

Quick start:

Kotlin
FaceCaptureSDK.register(this)  // in onCreate

FaceCaptureSDK.start(activity) { result ->
    when (result) {
        is FaceCaptureResult.Success -> {
            val file   = ImageUtils.bitmapToFile(context, result.bitmap)
            val base64 = ImageUtils.bitmapToBase64(result.bitmap)
            myBackend.callFaceGuardApi(file)  // never put API key in the app
        }
        FaceCaptureResult.Cancelled -> { }
        is FaceCaptureResult.Error  -> showError(result.message)
    }
}

⚠ Note

Never embed your FaceGuard API key in the app. Always proxy through your backend.
Full SDK docsAPI reference

Explore other APIs

Liveness Detection

Real-time anti-spoofing

Face Verification

Compare two faces with 4-model accuracy

Face Identification

Identify faces against enrolled users

Facial Analysis

Age, gender, emotion & ethnicity

Face Embeddings

Extract base64 face vectors

Ready to integrate Face Search?

Create a free account. Get 50 test API requests instantly — no credit card required.

Get started free Read the docs