Face Recognition API Documentation (v2.2)

For ESP32 and other client integrations.

Base URL: http://: (e.g., http://20.68.131.221:5005)

Authentication Required: All API endpoints (except /, /docs, and /ping) now require an Authentication HTTP header. The value of this header must be the valid device/user UID.

Authentication: YOUR_DEVICE_UID

1. Recognize Faces in an Image

This section describes how to send an image for face recognition. The primary method for ESP32 is sending raw binary image data. An alternative multipart method is also available.

1.1 Recognize via Raw Binary Image (Recommended for ESP32)

This endpoint takes raw binary image data directly in the request body and attempts to identify known persons previously registered under the UID provided in the Authentication header. The response format (text or audio) depends on the user's preference.

Endpoint Details:

Method: POST
URL: /recognize_binary
Authentication: Required (UID in Authentication header).

Request Format:

The request body **is the raw binary image data** (e.g., JPEG, PNG bytes).

Required Headers:

Header Name	Example Value	Description
`Authentication`	`YOUR_DEVICE_UID`	The unique device/user UID.
`Content-Type`	`image/jpeg`	Crucial. The MIME type of the image being sent (e.g., `image/jpeg`, `image/png`).

Example `curl` Request (Binary Body):

curl -X POST \
  http://:5005/recognize_binary \
  -H "Authentication: YOUR_DEVICE_UID" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@/path/to/scene_with_faces.jpg" \
  --output recognized_output --dump-header headers.txt
# Note: --data-binary sends the file content as raw binary.
# --output and --dump-header are for observing the response.

ESP32 Client Notes (Binary Upload):

This is generally simpler for ESP32.
Ensure the Authentication header is set.
**Must set the `Content-Type` header** correctly (e.g., "image/jpeg" if sending a JPEG from ESP32-CAM).
The HTTP request body should contain only the raw bytes of the image.

Response Format (Based on User Preference - Applies to both /recognize_binary and /recognize)

The server queries an external API to determine the user's preferred response format (Text or Audio) based on the authenticated UID. The HTTP status code (e.g., 200 OK or 500 Internal Server Error) remains a primary indicator of overall request success or critical failure.

A. Text Preference (or Audio Fallback)

HTTP Status Code: 200 OK (for successful processing, even if no faces are found/recognized) or 500 Internal Server Error (if there was a server-side issue like loading registered faces).
Headers:
- Content-Type: text/plain
- Result: 0
- X-Response-Type: ai_text (This type is used for all text responses, whether normal informational messages, successful recognitions, or error descriptions that are presented as text.)
- X-Response-Type: ai_text_fallback (This type is used if audio was preferred but TTS was unavailable, so a text response is provided instead. The content will be similar to ai_text.)

Body: Plain text string describing the outcome.

Examples:

I see Alice Wonderland.

I see one person, but I don't recognize them.

(Audio unavailable) No faces are registered for your user ID YOUR_DEVICE_UID.

Error loading registered faces for your user ID YOUR_DEVICE_UID. Please contact support.

I couldn't detect any faces in the image you sent.

B. Audio Preference

HTTP Status Code: 200 OK or 500 Internal Server Error (as above).
Headers:
- Content-Type: audio/x-raw (PCM, 16kHz, 16-bit Mono)
- Result: 1
- X-Response-Type: ai_audio (This type is used for all audio responses. The spoken content will indicate success, information, or an error.)
- Transfer-Encoding: chunked (Audio is streamed)
- X-Response-Text: (Optional, for client reference/debugging. Newlines removed. This text reflects what is spoken, be it success or an error description.)
Body: Streamed raw PCM audio data. The client needs to be able to play this format. The spoken audio will convey the result (e.g., "I see Alice," or "Error: No faces were detected").

Handling Responses on ESP32:

First, check the HTTP Status Code for overall success/failure of the API call.
Then, check the Result header (0 for Text, 1 for Audio) and Content-Type to determine how to process the body.
If audio (Result: 1, Content-Type: audio/x-raw), the client should read the body as a stream of raw audio bytes and send it to an appropriate audio output peripheral (e.g., I2S DAC).
The X-Response-Text header provides the text version of what was spoken, which can be useful for debugging or displaying if needed.
The content of the text or audio itself will describe the specific outcome of the recognition attempt (e.g., names recognized, no faces found, error messages).

General Error Responses (for /recognize_binary and /recognize, non-preference specific for critical client errors):

400 Bad Request:

(for /recognize_binary) Missing/invalid Content-Type header:
```
{"error": "Missing or invalid 'Content-Type' header..."}
```

(for /recognize_binary) No image data in body:

{"error": "No image data found in request body."}

(for /recognize multipart) Missing image file:
```
{"error": "No image file provided"}
```

401 Unauthorized: (Missing or malformed Authentication header)

{"error": "Authentication header required (containing UID)"}

403 Forbidden: (UID in Authentication header is invalid/unverified)

{"error": "Invalid or unverifiable UID"}

500 Internal Server Error: (e.g., major database issue before preference check. For other 500s where preference *can* be checked, it tries to use preferred format for the error message itself.)

{"error": "An internal error occurred."}

1.2 Recognize via Multipart Form Data (Alternative)

This endpoint also recognizes faces but expects the image as part of a multipart/form-data request. This might be used by clients other than ESP32 or if the ESP32 library handles multipart better for some reason.

Endpoint Details:

Method: POST
URL: /recognize
Authentication: Required (UID in Authentication header).

Request Format (Multipart):

The request must be a multipart/form-data POST request.

Required Headers:

Authentication: YOUR_DEVICE_UID

Form Fields:

Field Name	Type	Description	Required
`image`	File (image/jpeg, image/png)	The image file captured by the device, containing faces to be recognized.	Yes

Example `curl` Request (Multipart):

curl -X POST \
  http://:5005/recognize \
  -H "Authentication: YOUR_DEVICE_UID" \
  -F "image=@/path/to/scene_with_faces.jpg" \
  --output recognized_output --dump-header headers.txt

Response Format: Same as for /recognize_binary (see section 1.1 Response Format above).

2. Register a New Face

This endpoint allows you to register one or more images for a specific person. The UID for registration is taken from the Authentication header.

Endpoint Details:

Method: POST
URL: /register
Authentication: Required (UID in Authentication header).

Request Format:

The request must be a multipart/form-data POST request.

Required Headers:

Authentication: YOUR_DEVICE_UID

Form Fields:

Field Name	Type	Description	Required
`name`	String	The name of the person whose face is being registered. This name will be used in recognition responses.	Yes
`image`	File (image/jpeg, image/png)	The image file containing a clear, single face to be registered.	Yes

Example `curl` Request:

curl -X POST \
  http://:5005/register \
  -H "Authentication: YOUR_DEVICE_UID" \
  -F "name=Alice Wonderland" \
  -F "image=@/path/to/alice_center.jpg"

ESP32 Client Notes (Register):

Ensure the Authentication header is set with the device UID.
Construct a multipart/form-data request. Libraries like `HTTPClient` on ESP32 can help manage this.
Send one image per request for optimal registration.

Registration Image Guidance:

For robust recognition, especially with variable camera quality like ESP32-CAM, we **strongly recommend registering multiple photos per person**. Call the /register endpoint multiple times (once for each photo) with the same Authentication header UID and the same name, but a different image file.

Suggested poses/conditions for registration images (clear, well-lit, single face):

Center (Neutral): Looking directly at the camera, neutral expression.
Center (Smiling): Looking directly at the camera, smiling.
Look Left (Slightly): Head turned slightly to their left.
Look Right (Slightly): Head turned slightly to their right.
(Optional) Images from the ESP32-CAM itself under typical operating conditions.

Aim for **3-5 diverse images per person**. The API registers the first face detected in the submitted image.

Success Response (201 Created):

{
    "message": "Successfully registered face for Alice Wonderland under authenticated UID YOUR_DEVICE_UID"
}

Error Responses (Register):

400 Bad Request: (e.g., missing fields, no face in image, name empty)

{"error": "No face found in the provided image"}

401 Unauthorized: (Missing or malformed Authentication header)

{"error": "Authentication header required (containing UID)"}

403 Forbidden: (UID in Authentication header is invalid/unverified)

{"error": "Invalid or unverifiable UID"}

500 Internal Server Error: (e.g., database issue)

{"error": "Database error during registration."}

3. Manage Registered Faces

These endpoints allow listing and deleting registered face entries for the authenticated UID.

3.1 List Registered Faces

Retrieves a list of all face entries (individual image registrations) associated with the authenticated UID.

Endpoint Details:

Method: GET
URL: /faces/list
Authentication: Required (UID in Authentication header).

Example `curl` Request:

curl -X GET \
  http://:5005/faces/list \
  -H "Authentication: YOUR_DEVICE_UID"

Success Response (200 OK):

If faces are registered:

{
    "message": "Successfully retrieved registered faces.",
    "registered_face_entries": [
        {"id": 1, "name": "Alice"},
        {"id": 2, "name": "Bob"},
        {"id": 5, "name": "Alice"} 
    ]
}

If no faces are registered:

{
    "message": "No faces are currently registered for this UID.",
    "registered_persons": [] 
}

The id in each entry is the unique database identifier for that specific image registration. It is used for deletion.

Error Responses (List Faces):

401 Unauthorized / 403 Forbidden: Standard authentication errors.

500 Internal Server Error: (e.g., database issue)

{"error": "A database error occurred while retrieving face list."}

3.2 Delete a Specific Face Entry

Deletes a single registered face entry using its unique id. The entry must belong to the authenticated UID.

Endpoint Details:

Method: DELETE
URL: /faces/delete/ (Replace with the actual ID from the list, e.g., /faces/delete/5)
Authentication: Required (UID in Authentication header).

URL Parameters:

Parameter	Type	Description
	Integer	The unique ID of the face entry to delete (obtained from the `/faces/list` endpoint).

Example `curl` Request:

curl -X DELETE \
  http://:5005/faces/delete/5 \
  -H "Authentication: YOUR_DEVICE_UID"

Success Response (200 OK):

{
    "message": "Successfully deleted face entry for 'Alice' (ID: 5)."
}

Error Responses (Delete Face):

401 Unauthorized / 403 Forbidden: Standard authentication errors.

404 Not Found: If the face_id does not exist, or if it exists but does not belong to the authenticated UID.

{"error": "Face entry not found or not authorized for deletion."}

500 Internal Server Error: (e.g., database issue)

{"error": "A database error occurred during face deletion."}

4. Ping (Health Check)

A simple endpoint to check if the server is alive and responding. Does not require authentication.

Endpoint Details:

Method: GET
URL: /ping
Authentication: Not Required.

Success Response (200 OK):

{
    "message": "Pong! Face Recognition Server is alive."
}

ESP32-CAM Image Quality: The reliability of face recognition heavily depends on the image quality provided by the ESP32-CAM. Poor lighting, motion blur, low resolution, and incorrect focus will significantly reduce accuracy. Optimize image capture on the ESP32 side as much as possible.

1. Recognize Faces in an Image

1.1 Recognize via Raw Binary Image (Recommended for ESP32)

Endpoint Details:

Request Format:

Required Headers:

Example curl Request (Binary Body):

Response Format (Based on User Preference - Applies to both /recognize_binary and /recognize)

A. Text Preference (or Audio Fallback)

B. Audio Preference

General Error Responses (for /recognize_binary and /recognize, non-preference specific for critical client errors):

1.2 Recognize via Multipart Form Data (Alternative)

Endpoint Details:

Request Format (Multipart):

Required Headers:

Form Fields:

Example curl Request (Multipart):

2. Register a New Face

Endpoint Details:

Request Format:

Required Headers:

Form Fields:

Example curl Request:

Registration Image Guidance:

Success Response (201 Created):

Error Responses (Register):

3. Manage Registered Faces

3.1 List Registered Faces

Endpoint Details:

Example curl Request:

Success Response (200 OK):

Error Responses (List Faces):

3.2 Delete a Specific Face Entry

Endpoint Details:

URL Parameters:

Example curl Request:

Success Response (200 OK):

Error Responses (Delete Face):

4. Ping (Health Check)

Endpoint Details:

Success Response (200 OK):

Example `curl` Request (Binary Body):

Example `curl` Request (Multipart):

Example `curl` Request:

Example `curl` Request:

Example `curl` Request: