API Reference - face-engine

Base URL

There’s no path prefix beyond /v1 — the service is meant to sit behind a gateway that handles routing/TLS/auth. Locally, that’s:

http://localhost:8080

Endpoints at a glance

Method	Path	Purpose
`POST /v1/embed`	Detect + embed a single face
`POST /v1/compare`	Compare two faces, get a similarity score
`GET /v1/health`	Liveness probe
`GET /v1/ready`	Readiness probe

Request format

Both /v1/embed and /v1/compare take multipart/form-data, not JSON — you’re uploading raw image bytes, not base64-encoding them into a JSON body. Field names are documented per-endpoint.

Error format

Every error response is JSON with at minimum an error key, and a field key when the error is specific to one of multiple uploaded images (/v1/compare only):

{ "error": "no_face_detected", "field": "image2" }

`error` value	Status	Meaning
`invalid_multipart_body`	400	Request body isn’t valid multipart
`missing_field_image`	400	`/v1/embed`: no `image` field present
`missing_field_image1_or_image2`	400	`/v1/compare`: one or both fields missing
`empty_upload`	422	File field was present but empty
`upload_too_large`	422	File exceeds 10 MB
`undecodable_image`	422	Bytes don’t decode as a supported image format
`image_dimensions_exceed_limit`	422	Image exceeds 4096px on either axis
`image_too_small`	422	Image is under 20px on either axis
`no_face_detected`	422	Decoded fine, but no face found above threshold

See Architecture → ImageUtils for exactly where each check happens and why.

Upload limits

Per-file: 10 MB (ImageUtils::kMaxUploadBytes)
Total request body: 12 MB (Drogon’s setClientMaxBodySize, in main.cpp) — gives headroom for multipart boundaries/headers over two 10 MB files in /v1/compare, but two files close to the per-file limit can still combine to exceed this and get a 413 from Drogon itself (before your handler even runs).
Dimensions: 20px–4096px on both axes.

These are compile-time constants (src/ImageUtils.h), not currently environment-configurable. If you need different limits, that’s a code change, not a config change.