README.md

---
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.