README.md

metadata

title: Face Recognition API
emoji: 🧠
colorFrom: yellow
colorTo: blue
sdk: gradio
app_file: app.py
pinned: false

Face Recognition API

InsightFace buffalo_l face recognition service for SchoolMaster attendance. Stateless — it only extracts/compares face embeddings. All student data (including embeddings) lives in your MySQL database, not on this Space.

Visiting the Space shows a small status page (Gradio) — that's just a health-check UI. Your PHP backend talks directly to the /api/* endpoints below, not to that page.

Required setup: add your API key as a Secret

Do not put your API key in this README or in any committed file.

1. On this Space, go to Settings → Repository secrets (or Variables and secrets, depending on your account).
2. Add a secret named API_KEY with your real key as the value — the same value your PHP .env uses to call this service.
3. Restart the Space.

config.py reads it via os.environ — it is never written into the repo.

Endpoints (same contract as your local version — no PHP changes needed)

Endpoint	Method	Description
/api/health	GET	Health check
/api/extract	POST	Extract embedding from 1+ photos (multipart files)
/api/enroll	POST	Extract + average embedding from 3-10 photos (multipart files)
/api/recognize	POST	Match one photo against embeddings you pass in

All POST endpoints require an X-API-Key header matching your API_KEY secret, and accept multipart/form-data file uploads — identical to your local FastAPI service, so your existing PHP integration works unchanged (just point it at this Space's URL instead of 127.0.0.1:8000).

What was actually wrong before

The previous version tried to run a second uvicorn server in a background thread on the same port Gradio also wanted to use, and never blocked the main thread — so the process exited right after a successful model load, crash-looping the Space. This version runs everything (the API routes and a small Gradio status page) as one process on one port, which is what Spaces actually needs.

A tradeoff to know about before relying on this for production

Free-tier Spaces:

• Sleep after inactivity. The first request after a sleep can take 1-2 minutes while the container restarts and re-downloads the model.
• CPU-only, similar to or slower than a typical laptop — this may not fix the "too slow" complaint that prompted looking at this in the first place. Worth timing actual /api/recognize calls here vs. your local setup before switching your kiosk over to it.