face-lock is a standalone FastAPI image-processing service that detects a primary subject, expands it to a square crop, and returns either structured JSON previews or a binary JPEG crop. It is designed to be deployable as a small production service, not just a local experiment.

What it does

Accepts a single uploaded image.
Detects the main subject with one of four detectors: face, animal, person, or subject.
Applies a configurable square buffer around the chosen bounding box.
Returns either:
- JSON metadata plus crop_data_url and annotated_data_url at POST /api/focus
- A cropped JPEG image at POST /api/focus/image

Endpoints

GET /health
GET /
POST /api/focus
POST /api/focus/image
GET /docs
GET /openapi.json

Runtime defaults

Docs are enabled by default: FACE_LOCK_DOCS=true
Test UI is disabled by default: FACE_LOCK_TEST_UI=false
Maximum upload size defaults to 8388608 bytes
Allowed MIME types default to image/jpeg,image/png,image/webp,image/gif
Optional shared-token auth is enabled by setting FACE_LOCK_AUTH_TOKEN

Supported auth headers:

X-API-Key: <token>
Authorization: Bearer <token>

You can override the custom header name with FACE_LOCK_AUTH_HEADER.

Local development

cp .env.example .env
python -m pip install -r requirements.txt
python -m pytest
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Docker

docker compose up --build

The image now runs as a non-root user and includes a built-in healthcheck. If you change values in .env, recreate the container so Compose reloads the env file:

docker compose up -d --force-recreate

Production notes

Set FACE_LOCK_AUTH_TOKEN before exposing the service publicly.
Keep FACE_LOCK_TEST_UI=false in production-style environments.
Tune WEB_CONCURRENCY based on CPU and workload.
The service is stateless and safe to run behind a reverse proxy or container orchestrator.

More docs

Project notes: docs/README.md
Repo working rules: CLAUDE.md