Overview

The FacialProof Face Detect API analyzes images and returns information about every face found. You send a single image (as Base64-encoded data in the request body), and the API returns the number of faces detected plus optional attributes such as age range, emotion, and gender for each face.

Typical use cases include:

• Verifying that a photo contains a face (e.g. for identity or liveness checks)
• Getting demographic or emotion data for analytics or personalization
• Obtaining bounding boxes for each face for cropping or overlay

Supported image formats are JPG and PNG. The image must be sent in the request body as a Base64-encoded string. All requests and responses use JSON.

Base URL

All API requests go to the following base URL. Endpoints are paths appended to this base.

https://api.facialproof.com

Authentication

Every request must include your API key so the service can identify and authorize your account. Send the key in the X-API-Key HTTP header. You can obtain an API key from your FacialProof dashboard or when you sign up.

Always use HTTPS in production and keep your API key secret. Do not expose it in client-side code or public repositories.

Required headers:

X-API-Key: YOUR_API_KEY
Content-Type: application/json

POST /v1/face/detect

This endpoint accepts one image, detects all faces in it, and returns metadata for each face. Send the image as a Base64 string in the JSON body. You can turn on or off emotion detection, age estimation, and gender estimation via the request parameters.

On success the API responds with 200 OK and a JSON object containing success, faces_detected, and a faces array. Each element in faces includes an id, confidence, bounding_box (x, y, width, height), and—when requested—age, emotion, and gender.

Request

Use a POST request with Content-Type: application/json and the headers shown below. The body must be valid JSON.

POST https://api.facialproof.com/v1/face/detect HTTP/1.1
Content-Type: application/json
X-API-Key: YOUR_API_KEY

Body (JSON)

• image — (required) The image as a Base64-encoded string (e.g. from a file or camera).
• detect_emotions — (optional) If true, the API returns an emotion label per face (e.g. Happy, Neutral).
• detect_age — (optional) If true, returns an age range per face (e.g. “27-29 years old”).
• detect_gender — (optional) If true, returns a gender label per face.

{
    "image": "base64_encoded_image_data",
    "detect_emotions": true,
    "detect_age": true,
    "detect_gender": false
}

Response

On success you receive 200 OK and a JSON object with success, faces_detected (count), and faces (array of face objects). Each face object includes id, confidence (0–1), bounding_box with x, y, width, height, and—when requested—age, emotion, and gender.

200 OK
Content-Type: application/json

{
    "success": true,
    "faces_detected": 3,
    "faces": [
        {
            "id": 1,
            "confidence": 0.95,
            "bounding_box": {
                "x": 150,
                "y": 200,
                "width": 300,
                "height": 350
            },
            "age": "27-29 years old",
            "emotion": "Happy",
            "gender": "Female"
        },
        {
            "id": 2,
            "confidence": 0.92,
            "bounding_box": {
                "x": 500,
                "y": 180,
                "width": 280,
                "height": 320
            },
            "age": "25-27 years old",
            "emotion": "Neutral",
            "gender": "Male"
        }
    ]
}

Code sample

Below is a complete example in PHP that encodes an image, sends a POST request to the Face Detect endpoint, and reads the JSON response. Replace YOUR_API_KEY with your actual API key and adjust the image path or source as needed.

$url = "https://api.facialproof.com/v1/face/detect";
$image_b64 = base64_encode(file_get_contents("photo.jpg"));
$payload = json_encode([
    "image" => $image_b64,
    "detect_emotions" => true,
    "detect_age" => true,
    "detect_gender" => false
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-API-Key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);