# face-lock docs

## Overview

`face-lock` is a FastAPI service for square subject crops. It uses OpenCV-based
detectors, returns stable JSON metadata for preview workflows, and can also
stream the cropped JPEG directly for simple image pipelines.

## Endpoints

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

## Detector modes

- `face` for frontal human faces
- `animal` for pets and animals, with contour fallback
- `person` for full-body people detection
- `subject` for generic foreground contour detection

## Request validation

- Uploads must be non-empty.
- Uploads must stay below `FACE_LOCK_MAX_UPLOAD_BYTES`.
- Content types must match `FACE_LOCK_ALLOWED_MIME_TYPES`.
- `buffer_ratio` is clamped at the API layer to the `0.0` to `0.6` range.

## Authentication

Set `FACE_LOCK_AUTH_TOKEN` to require a shared secret.

Supported forms:

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

Optional override:

- `FACE_LOCK_AUTH_HEADER`

## Example

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

Binary crop response:

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

## Container notes

- The production image runs as a non-root user.
- The container includes a `/health` healthcheck.
- Compose runs the root filesystem read-only and mounts `/tmp` as tmpfs.

If you change `.env`, recreate the container:

```bash
docker compose up -d --force-recreate
```