Face Recognition API Actor Advanced facial analysis and identification Actor for the Apify platform. Process images and videos to detect, analyze, and match human faces using state-of-the-art computer vision algorithms powered by DeepFace. ## 🎯 Key Features - Real-time Face Detection: Achieves high accuracy rates (up to 98.4%) in identifying faces - Facial Landmark Identification: Provides detailed feature mapping for each detected face - Emotion & Demographic Analysis: Estimates age, gender, and emotional states - Batch Processing: Handles multiple images or video files simultaneously - Custom Database Face Matching: Match faces against user-defined databases (1:N matching) - Versatile Media Extraction: Supports various image formats and video processing - Privacy Compliant: Secure data handling with privacy best practices ## 🚀 Quick Start ### Basic Usage json { "inputType": "imageUrls", "imageUrls": [ "https://example.com/photo1.jpg", "https://example.com/photo2.jpg" ], "performFaceDetection": true, "performFacialAnalysis": true, "detectorBackend": "opencv", "recognitionModel": "Facenet512" } ### Video Processing json { "inputType": "videoUrls", "videoUrls": ["https://example.com/video.mp4"], "videoFrameSamplingRate": 1, "performFaceDetection": true, "performFacialAnalysis": true } ### Database Matching json { "inputType": "imageUrls", "imageUrls": ["https://example.com/target.jpg"], "performDatabaseMatching": true, "databaseKeyValueStoreName": "my-face-database", "databaseSimilarityThreshold": 0.6 } ## 📊 Input Parameters ### Input Source | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | inputType | string | Type of input: imageUrls, videoUrls, or datasetId | imageUrls | | imageUrls | array | List of image URLs to process | [] | | videoUrls | array | List of video URLs to process | [] | | datasetId | string | Apify Dataset ID containing images | - | ### Detection & Recognition | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | detectorBackend | string | Face detector: opencv (fast), retinaface (accurate), mtcnn, ssd, dlib | opencv | | recognitionModel | string | Recognition model: Facenet512, VGG-Face, ArcFace, etc. | Facenet512 | | detectionConfidence | number | Minimum confidence threshold (0.0-1.0) | 0.9 | ### Feature Flags | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | performFaceDetection | boolean | Enable face detection | true | | performFacialAnalysis | boolean | Analyze age, gender, emotion, race | true | | performLandmarkDetection | boolean | Detect facial landmarks | false | | performDatabaseMatching | boolean | Match against custom database | false | ### Database Settings | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | databaseKeyValueStoreName | string | Name of Key-Value Store for face database | face-database | | databaseSimilarityThreshold | number | Similarity threshold for matching (0.0-1.0) | 0.6 | ### Processing Options | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | videoFrameSamplingRate | integer | Frames per second to extract from videos | 1 | | maxFacesPerImage | integer | Maximum faces to process per image (0 = unlimited) | 0 | | batchSize | integer | Number of images to process in parallel | 5 | | maxResults | integer | Maximum number of images to process (0 = unlimited) | 0 | | saveAnnotatedImages | boolean | Save images with bounding boxes | false | | saveFaceCrops | boolean | Save individual face crops | false | ## 📤 Output Format ### Image Result json { "imageUrl": "https://example.com/photo.jpg", "timestamp": "2024-11-19T21:00:00.000Z", "processingTimeSeconds": 2.34, "facesDetected": 2, "faces": [ { "faceId": 0, "boundingBox": { "x": 100, "y": 150, "w": 120, "h": 140 }, "detectionConfidence": 0.99, "analysis": { "age": 28, "gender": { "class": "Woman", "confidence": 98.5 }, "emotion": { "class": "happy", "confidence": 87.3 }, "race": { "class": "white", "confidence": 76.2 } }, "databaseMatches": [ { "databaseId": "person_123", "name": "John Doe", "similarity": 0.89, "distance": 0.11 } ] } ] } ### Summary Statistics The Actor also saves a summary with aggregated statistics: json { "totalImagesProcessed": 10, "totalFacesDetected": 23, "averageFacesPerImage": 2.3, "totalProcessingTimeSeconds": 45.6, "averageProcessingTimePerImage": 4.56, "emotionDistribution": { "happy": 12, "neutral": 8, "sad": 3 }, "genderDistribution": { "Woman": 14, "Man": 9 }, "ageStatistics": { "averageAge": 32.4, "minAge": 18, "maxAge": 65 } } ## 🎯 Use Cases ### Security & Access Control - Building access control systems - Identity verification for secure areas - Employee attendance tracking - Surveillance footage analysis ### Marketing & Demographics - Analyze customer demographics from store cameras - Measure audience engagement at events - A/B testing with facial emotion detection - Target audience analysis from visual content ### Social Media & Content Moderation - Automated face blurring for privacy - Content categorization by demographics - Finding specific individuals in large photo collections - Duplicate face detection ### Law Enforcement - Suspect identification from surveillance - Missing person searches - Witness identification - Evidence processing ## 🗄️ Custom Face Database ### Creating a Database To match faces against a custom database, you'll need to populate a Key-Value Store with face embeddings: 1. Option A: Use this Actor to build a database - Process reference images with performDatabaseMatching: false - Extract embeddings from results - Store in Key-Value Store 2. Option B: Use the Apify API javascript const store = await Actor.openKeyValueStore('my-face-database'); await store.setValue('face_john_doe', { id: 'john_doe', name: 'John Doe', embedding: [...], // 128/512-dimensional vector metadata: { department: 'Engineering' } }); ### Database Format Each face entry should follow this structure: json { "id": "unique_id", "name": "Person Name", "embedding": [0.123, -0.456, ...], "embedding_dimension": 512, "metadata": { "custom_field": "value" } } ## ⚙️ Model Selection ### Detector Backends | Backend | Speed | Accuracy | Best For | |---------|-------|----------|----------| | opencv | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | Real-time processing, large batches | | retinaface | ⭐⭐ | ⭐⭐⭐⭐⭐ | High accuracy requirements | | mtcnn | ⭐⭐ | ⭐⭐⭐⭐⭐ | Challenging lighting/angles | | ssd | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Balanced performance | | dlib | ⭐⭐⭐ | ⭐⭐⭐⭐ | General purpose | ### Recognition Models | Model | Accuracy | Speed | Dimension | Best For | |-------|----------|-------|-----------|----------| | Facenet512 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | 512 | Recommended - Best overall accuracy | | ArcFace | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | 512 | High accuracy matching | | VGG-Face | ⭐⭐⭐⭐ | ⭐⭐ | 2622 | Research applications | | Facenet | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 128 | Fast processing | | OpenFace | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 128 | Speed-critical applications | ## 🔒 Privacy & Compliance ### Important Considerations > ⚠️ WARNING: This Actor processes biometric data. Ensure compliance with applicable privacy regulations: > - GDPR (Europe): Obtain explicit consent, implement data minimization > - CCPA (California): Provide opt-out mechanisms, disclose data usage > - BIPA (Illinois): Get written consent before collecting biometric data > - Other jurisdictions: Check local laws ### Best Practices 1. Obtain Consent: Always get explicit permission before processing faces 2. Data Minimization: Only collect/process data necessary for your use case 3. Secure Storage: Use Apify's encrypted storage for sensitive data 4. Retention Policies: Define and enforce data retention limits 5. Access Controls: Restrict access to face data and databases 6. Anonymization: Consider anonymizing results when possible ## 🔧 Integration Examples ### JavaScript/Node.js javascript const { ApifyClient } = require('apify-client'); const client = new ApifyClient({ token: 'YOUR_API_TOKEN' }); const run = await client.actor('YOUR_ACTOR_ID').call({ inputType: 'imageUrls', imageUrls: ['https://example.com/photo.jpg'], performFacialAnalysis: true }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ### Python python from apify_client import ApifyClient client = ApifyClient('YOUR_API_TOKEN') run = client.actor('YOUR_ACTOR_ID').call(run_input={ 'inputType': 'imageUrls', 'imageUrls': ['https://example.com/photo.jpg'], 'performFacialAnalysis': True }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ### cURL bash curl -X POST https://api.apify.com/v2/acts/YOUR_ACTOR_ID/runs \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputType": "imageUrls", "imageUrls": ["https://example.com/photo.jpg"], "performFacialAnalysis": true }' ## 📈 Performance ### Processing Times (Approximate) | Configuration | Images/minute | Notes | |---------------|---------------|-------| | OpenCV + Facenet512 | 30-40 | Recommended for most use cases | | RetinaFace + ArcFace | 10-15 | Highest accuracy | | OpenCV + OpenFace | 50-60 | Speed-optimized | ### Resource Requirements - Memory: Minimum 2048 MB (4096 MB recommended for large batches) - Compute: Scales with image resolution and number of faces ## 🐛 Troubleshooting ### No Faces Detected - Lower detectionConfidence threshold - Try different detectorBackend (e.g., retinaface for difficult images) - Ensure images are clear and faces are visible - Check image resolution (very small faces may not be detected) ### Poor Recognition Accuracy - Use Facenet512 or ArcFace models for best accuracy - Ensure reference database has good quality images - Adjust databaseSimilarityThreshold (lower = more strict) - Verify face alignment and image quality ### Slow Processing - Use opencv detector for faster processing - Reduce batchSize if running out of memory - Use OpenFace model for faster recognition - Process videos at lower videoFrameSamplingRate ### Memory Issues - Reduce batchSize - Set maxFacesPerImage to limit processing - Disable saveAnnotatedImages and saveFaceCrops - Process images in smaller batches ## 📚 Additional Resources - DeepFace Documentation - Apify Documentation - Face Recognition Best Practices - Privacy Regulations Guide ## 🤝 Support For issues, questions, or feature requests: - Open an issue on GitHub - Contact Apify support - Check the Apify Community Forum ## 📝 License Apache-2.0 --- Built with ❤️ using Apify and DeepFace