# face-lock docs

## Overview

face-lock is a FastAPI service that detects a primary subject, makes a square crop, and returns both a crop and an annotated preview. The app ships with a simple Tailwind test UI at `/`.

## Endpoints

- `GET /health`
- `GET /`
- `POST /api/focus`
- `POST /api/focus/image`
- `GET /docs`

## Detectors

- `face` for human faces
- `animal` for pets / animals, with a contour fallback
- `person` for full-body person detection
- `subject` for general foreground subjects

## Test UI

Set `FACE_LOCK_TEST_UI=false` to disable the `/` test UI. If you update `.env`, recreate the container so Docker picks up the new values.

## Authentication

Set `FACE_LOCK_AUTH_TOKEN` to require a header token.

Supported headers:

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

Optional override:

- `FACE_LOCK_AUTH_HEADER` changes the expected header name.

## Example

```bash
curl -H 'X-API-Key: your-token' \
  -F 'file=@image.jpg' \
  -F 'detector=animal' \
  http://localhost:8000/api/focus
```

## Docker note

Use `docker compose up -d --force-recreate` after env changes.