DeepFace API v1.1.1: Custom Threshold Parameter

Overview

We're excited to release DeepFace API v1.1.0, which introduces a powerful new feature: custom threshold parameters for face verification. This enhancement gives you greater control over face-matching sensitivity, allowing you to fine-tune your application's face verification requirements.

New Features

Custom Threshold Parameter for Face Verification

• Adjustable Matching Sensitivity: Fine-tune the confidence level required for face matches
• Full Backward Compatibility: API continues to work with existing code using default thresholds
• Extensive Testing: Verified across development, staging, and production environments

Implementation Details

The /verify endpoint now accepts an optional threshold parameter in the request body. This parameter allows you to override the default threshold value for the selected model.

Default Thresholds by Model

Model	Default Threshold
VGG-Face	0.4
Facenet	0.4
Facenet512	0.3
OpenFace	0.1
DeepFace	0.23
DeepID	0.015
ArcFace	0.68
Dlib	0.7
SFace	0.593

Usage Examples

Python Example

import requests

api_url = "https://deepface-workweek.fly.dev"
api_key = "your_api_key"

# Request payload with custom threshold
payload = {
    "img1": "https://example.com/person1.jpg",
    "img2": "https://example.com/person2.jpg",
    "model_name": "Facenet512",
    "threshold": 0.5  # More lenient than default (0.3)
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": api_key
}

response = requests.post(f"{api_url}/verify", json=payload, headers=headers)
result = response.json()
print(f"Verified: {result['verified']}")
print(f"Distance: {result['distance']}")
print(f"Threshold used: {result['threshold']}")

JavaScript/Node.js Example

const axios = require('axios');

const apiUrl = 'https://deepface-workweek.fly.dev';
const apiKey = 'your_api_key';

// Request with custom threshold
const payload = {
  img1: 'https://example.com/person1.jpg',
  img2: 'https://example.com/person2.jpg',
  model_name: 'Facenet512',
  threshold: 0.2  // Stricter than default (0.3)
};

const headers = {
  'Content-Type': 'application/json',
  'X-API-Key': apiKey
};

axios.post(`${apiUrl}/verify`, payload, { headers })
  .then(response => {
    console.log(`Verified: ${response.data.verified}`);
    console.log(`Distance: ${response.data.distance}`);
    console.log(`Threshold used: ${response.data.threshold}`);
  })
  .catch(error => console.error('Error:', error));

When to Adjust Thresholds

• Lower thresholds (stricter): Reduce false positives when you need higher confidence
• Higher thresholds (more lenient): Reduce false negatives when you need to match more faces

Bug Fixes

• None in this release

Breaking Changes

• None - this is a fully backward-compatible enhancement

Installation/Upgrade

No action required - the API has been updated on all environments:

• Development: https://deepface-workweek-dev.fly.dev
• Staging: https://deepface-workweek-staging.fly.dev
• Production: https://deepface-workweek.fly.dev

Acknowledgements

Thanks to the entire WorkWeek team for their contributions to this release.