moonsunkey/siamese-api

👥 Siamese Network Face Similarity API

A REST API for detecting face similarity and duplicates using a Siamese Neural Network with ResNet18 backbone.

🚀 API Endpoints

POST /predict

Compare two face images and get similarity score.

Parameters:

• —image1: First face image file (JPEG, PNG)
• —image2: Second face image file (JPEG, PNG)

Response:

{
  "similarity_score": 0.95,
  "is_duplicate": true,
  "threshold_used": 0.9,
  "confidence": "high"
}

Confidence levels:

• —high: similarity > 0.95
• —medium: similarity > 0.8
• —low: similarity ≤ 0.8

GET /health

Check if the API is running and model is loaded.

Response:

{
  "status": "healthy",
  "model": "loaded",
  "device": "cpu"
}

GET /

Get API information and available endpoints.

📖 Usage Examples

Python

import requests

url = "https://moonsunkey-siamese-api.hf.space/predict"

files = {
    'image1': open('person1.jpg', 'rb'),
    'image2': open('person2.jpg', 'rb')
}

response = requests.post(url, files=files)
result = response.json()

print(f"Similarity: {result['similarity_score']}")
print(f"Is Duplicate: {result['is_duplicate']}")

cURL

curl -X POST "https://moonsunkey-siamese-api.hf.space/predict" \
  -F "image1=@face1.jpg" \
  -F "image2=@face2.jpg"

JavaScript/Fetch

const formData = new FormData();
formData.append('image1', file1);
formData.append('image2', file2);

fetch('https://moonsunkey-siamese-api.hf.space/predict', {
  method: 'POST',
  body: formData
})
.then(res => res.json())
.then(data => console.log(data));

🎯 Use Cases

• —Duplicate Account Detection: Prevent users from creating multiple accounts with the same face
• —Face Verification: Verify if two images contain the same person
• —Identity Matching: Match faces across different images
• —Security Systems: Enhance authentication systems

⚙️ Model Details

• —Architecture: Siamese Network with ResNet18 backbone
• —Input Size: 224x224 RGB images
• —Output: Similarity score (0.0 to 1.0)
• —Duplicate Threshold: 0.9 (configurable)

🔒 Privacy & Security

• —Images are processed in real-time and not stored
• —All processing happens on Hugging Face infrastructure
• —No data is logged or saved

📝 License

MIT License

🤝 Support

For issues or questions, please open an issue on the repository.