API FAQ

Answers to the most common questions about usage, limits and integration.

Frequently Asked Questions (FAQ)

Account & Billing

How do I create an account?

Visit the registration page, enter your email, username, and password. You'll automatically get a Free plan with 2,000 requests per month.

Is there a free trial?

Yes! Every new user starts with a Free plan that includes 2,000 requests per month. No credit card required.

How do I upgrade my plan?

Contact our sales team at sales@yoursystem.com or visit the pricing page on your dashboard.

Can I downgrade my plan?

Yes, you can downgrade at any time. Changes take effect at the start of your next billing cycle.

What payment methods do you accept?

We accept credit cards (Visa, Mastercard, American Express), PayPal, and bank transfers for Enterprise plans.

Do you offer refunds?

We offer a 30-day money-back guarantee for Pro and Enterprise plans. Contact support@yoursystem.com.

Rate Limits & Usage

What counts as a "request"?

Every API call that performs face recognition, saves a face, searches the database, or updates face information counts as one request.

What happens if I exceed my rate limit?

You'll receive a 429 error response. The system will tell you when your limit resets:

  • Hourly limits reset every 60 minutes
  • Daily limits reset at midnight UTC
  • Monthly limits reset 30 days from your billing date

Can I purchase additional requests?

Yes! Contact us to add request packs to your existing plan.

Do failed requests count toward my limit?

No. Only successful requests (HTTP 200 responses) count toward your limits.

How can I monitor my usage?

  • Use the /auth/rate-limit-status/ API endpoint
  • View usage statistics on your dashboard
  • Set up email alerts for usage thresholds

What are "trained tags"?

Trained tags are unique faces/identities in your database that the system has learned to recognize.

Technical Questions

What image formats are supported?

  • JPG/JPEG
  • PNG
  • Maximum file size: 10MB
  • Recommended resolution: 640x480 or higher

How accurate is the face recognition?

Our system achieves:

  • 99.5% accuracy on high-quality frontal face images
  • 95% accuracy on moderate-quality images
  • Accuracy decreases with poor lighting, angles, or low resolution

Can the system recognize multiple faces in one image?

The system detects the first/largest face in the image. For multiple faces, you need to make separate API calls for each face.

How long does face recognition take?

  • Typically 100-500ms per request
  • Depends on image size and server load
  • Large databases (100,000+ faces) may take up to 1 second

What data do you store?

We store:

  • Face images (encrypted)
  • Facial feature vectors (mathematical representations)
  • User-provided metadata (names, user IDs)
  • Detection logs

Is my data secure?

Yes! We use:

  • AES-256 encryption for stored data
  • TLS/SSL for data in transit
  • Regular security audits
  • GDPR-compliant data handling

Can I export my data?

Yes. Contact support to request a full data export in JSON or CSV format.

Do you train your AI on my data?

No. Your face data is only used for your account's recognition purposes. We do not use customer data to train our models.

Face Recognition

Why does the system say "No face detected"?

Common reasons:

  • Face is too small in the image
  • Poor lighting or very dark image
  • Face is at an extreme angle
  • Face is obscured (sunglasses, mask, etc.)
  • Image quality is too low

Solutions:

  • Use well-lit, clear images
  • Ensure face occupies at least 20% of the image
  • Face should be looking relatively forward
  • Remove sunglasses or face coverings

What is a "similarity score"?

A number from 0 to 1 (or 0% to 100%) indicating how similar two faces are:

  • 0.90-1.00: Excellent match (very likely same person)
  • 0.80-0.89: Good match (probably same person)
  • 0.70-0.79: Moderate match (possibly same person)
  • 0.60-0.69: Low confidence match
  • Below 0.60: Not a reliable match

How many images should I add per person?

For best results:

  • Minimum: 1 clear frontal image
  • Recommended: 3-5 images with different:
  • Lighting conditions
  • Angles (frontal, slight left, slight right)
  • Expressions
  • Time periods (to account for aging)

Can the system recognize faces with masks?

The system can detect faces with masks but recognition accuracy drops significantly. We recommend:

  • Using pre-mask images in your database
  • Training with both masked and unmasked photos
  • Considering eye-region recognition features

Does the system work with black and white photos?

Yes! The system works with both color and grayscale images. Color images generally provide slightly better results.

Can I recognize faces from video?

Yes, but you need to:

  1. Extract frames from video
  2. Send individual frames to the API
  3. Process results frame by frame

We recommend processing 1-2 frames per second rather than every frame.

API & Integration

What programming languages can I use?

Our REST API works with any language that can make HTTP requests:

  • Python
  • JavaScript/Node.js
  • Java
  • PHP
  • C#/.NET
  • Ruby
  • Go
  • And more!

Do you have SDKs or libraries?

Currently, we provide API documentation for direct REST API access. SDKs are coming soon for:

  • Python
  • JavaScript
  • Java

Can I use this on mobile apps?

Yes! You can integrate our API into:

  • iOS apps (Swift/Objective-C)
  • Android apps (Java/Kotlin)
  • React Native apps
  • Flutter apps
  • Xamarin apps

Is there a webhook feature?

Not currently. You need to poll the API for results. Webhooks are on our roadmap.

Can I run this on-premise?

Enterprise customers can request on-premise deployment. Contact sales@yoursystem.com.

What's the API rate limit for concurrent requests?

You can make up to 10 concurrent requests. More than 10 will be queued.

How do I handle errors in my code?

Always check HTTP status codes:

response = requests.post(url, json=data)
if response.status_code == 200:
    # Success
    result = response.json()
elif response.status_code == 429:
    # Rate limited - wait and retry
    time.sleep(3600)
elif response.status_code == 401:
    # Bad credentials
    print("Check your API key")

Features & Capabilities

Can I organize faces into groups?

Yes! Use the "namespaces" feature to organize faces into different projects or groups.

Can I search by name or user ID?

Yes. Use the search functionality in the web interface or filter API calls.

Is there a batch processing feature?

Not currently. You need to make individual API calls. Batch processing is on our roadmap.

Can I tag faces with custom metadata?

Currently, you can add:

  • Name
  • User ID
  • Active status

Custom metadata fields are coming in a future update.

Is there face liveness detection?

Not currently. This feature is on our roadmap and will help prevent spoofing attacks.

Can the system detect age, gender, or emotions?

No. Our system only does face recognition (identifying who the person is). Demographic or emotion detection is not available.

Troubleshooting

My API calls return 401 errors

Problem: Invalid credentials

Solutions:

  1. Check your API key and secret for typos
  2. Ensure there are no extra spaces
  3. Verify you're using the correct credentials
  4. Try regenerating your credentials from the dashboard

I'm getting 422 validation errors

Problem: Missing or invalid data in your request

Solutions:

  1. Check that all required fields are present
  2. Verify image is properly Base64 encoded
  3. Ensure JSON is properly formatted
  4. Check API documentation for correct field names

Recognition accuracy is poor

Solutions:

  1. Add more training images per person
  2. Use higher quality images
  3. Ensure proper lighting in photos
  4. Avoid extreme angles
  5. Update old photos if people have aged significantly

API is slow or timing out

Solutions:

  1. Check your internet connection
  2. Reduce image file size
  3. Compress images before uploading
  4. Check our status page for service issues
  5. Try during off-peak hours

I forgot my password

  1. Click "Forgot Password" on login page
  2. Enter your email
  3. Check your email for reset link
  4. Create new password

How do I delete my account?

Contact support@yoursystem.com with your account email. All your data will be permanently deleted within 30 days.

Best Practices

Image Quality Tips

✅ Do:

  • Use images at least 640x480 resolution
  • Ensure good, even lighting
  • Face should occupy 20-50% of image
  • Keep face upright and forward-facing
  • Use recent photos

❌ Don't:

  • Use blurry or grainy images
  • Extreme backlighting or shadows
  • Very small faces in large images
  • Extreme angles (profile views)
  • Heavy filters or effects

API Integration Tips

✅ Do:

  • Cache frequently used results
  • Implement exponential backoff for retries
  • Monitor your usage regularly
  • Handle errors gracefully
  • Use HTTPS for all requests

❌ Don't:

  • Store API credentials in your code
  • Make unnecessary repeated calls
  • Ignore rate limit warnings
  • Process every video frame (sample instead)
  • Skip error handling

Security Tips

✅ Do:

  • Store credentials in environment variables
  • Use secure HTTPS connections
  • Rotate credentials periodically
  • Monitor for unusual activity
  • Implement access logging

❌ Don't:

  • Share credentials with others
  • Commit credentials to Git
  • Use same credentials across environments
  • Ignore security alerts
  • Store credentials in plain text

Getting Help

How do I contact support?

  • Email: support@yoursystem.com
  • Phone: +1-XXX-XXX-XXXX
  • Live Chat: Available on dashboard (business hours)
  • Help Center: http://your-system-url/help

What information should I include in support requests?

  • Your username/email
  • Detailed description of the issue
  • Steps to reproduce the problem
  • Error messages (full text)
  • Screenshots if applicable
  • Your subscription plan

What are your support hours?

  • Email: 24/7 (response within 24 hours)
  • Live Chat: Monday-Friday, 9 AM - 5 PM EST
  • Phone: Monday-Friday, 9 AM - 5 PM EST
  • Emergency: 24/7 for Enterprise customers

Is there a community forum?

Coming soon! We're building a community forum where users can share tips and help each other.

Still Have Questions?

Can't find what you're looking for?

📧 Email us: support@yoursystem.com 💬 Chat with us: Available on your dashboard 📚 Read the full guide: Check out USER_GUIDE.md 🎓 Watch tutorials: Coming soon on our YouTube channel

We're here to help you succeed!