Face Service API

This service exposes a small REST API for face vectorization.

Base URL

• Default: http://<host>:9000

• The Docker container listens on port 9000.

  • Development (docker-compose.yml): starts uvicorn with the default of 1 worker (1 process) and access logs enabled.

  • Production (docker-compose.prod.yml): starts uvicorn with --workers 2 (two processes) and --no-access-log.

    • Each worker loads its own model copy.

Endpoints

GET /health

Health/readiness check.

Response

{"status":"ok"}

Not Ready (503)

Returned while the worker is still loading the model.

{"status":"not_ready"}

POST /faces/vectorize

Upload a face image as multipart/form-data and get its embedding.

Request

• Content-Type: multipart/form-data
• File field name: image (preferred) or file

Example (curl)

curl -F "image=@/path/to/face.jpg" http://localhost:9000/faces/vectorize

Success Response (200)

{
  "status": "success",
  "embedding": [0.0123, -0.0456, 0.0789]
}

Error Responses

• 400 {"status":"missing_image"}: no file uploaded
• 400 {"status":"invalid_image"}: unreadable or invalid image
• 422 {"status":"no_face"}: no face detected
• 422 {"status":"multiple_faces","face_count":2}: multiple faces detected
• 500 {"status":"error"}: internal error

Logging

The service logs one of the following outcomes for each request:

• Success: 1 face detected.
• Failure: no face detected.
• Failure: multiple faces detected.
• Failure: invalid image or server error.