# Face Detection API
> Detect human faces in an image and analyse each one with on-device machine learning: get the bounding box and a detection confidence, an estimated age, the predicted gender with its probability, and the dominant facial expression together with the full per-expression breakdown (neutral, happy, sad, angry, fearful, disgusted and surprised). A lightweight count endpoint returns just the number of faces and their boxes for fast gating. Supply an image by public URL, base64 or a raw binary request body; only public http/https URLs are accepted and private or internal hosts are blocked, and large images are downscaled automatically. Runs locally on TensorFlow (face-api) — no third-party upstream and no per-image cloud cost — with warm models that keep inference fast. Ideal for photo and avatar apps, audience analytics, smart cameras, auto-cropping and accessibility.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/facedetect-api/..."
```

## Pricing
- **Free** (Free) — 1,500 calls/Mo, 1 req/s
- **Basic** ($15/Mo) — 30,000 calls/Mo, 3 req/s
- **Pro** ($42/Mo) — 220,000 calls/Mo, 8 req/s
- **Mega** ($109/Mo) — 1,000,000 calls/Mo, 20 req/s

## Endpoints

### Face

#### `GET /v1/count` — Count faces (detection only)

**Parameters:**
- `url` (query, optional, string) — Image URL (or base64/raw body) Example: ``
- `base64` (query, optional, string) — Base64 image data Example: `iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAZElEQVR42u3QQREAAAgDoPUPuhqaw5MHBUjb+SwCBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIEDAfQsbYRN2hzEcHgAAAABJRU5ErkJggg==`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/facedetect-api/v1/count?url=&base64=iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAZElEQVR42u3QQREAAAgDoPUPuhqaw5MHBUjb%2BSwCBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIEDAfQsbYRN2hzEcHgAAAABJRU5ErkJggg%3D%3D"
```

**Response:**
```json
{
    "data": {
        "boxes": [],
        "count": 0
    },
    "meta": {
        "timestamp": "2026-05-31T03:47:41.047Z",
        "request_id": "16fb3d3f-c5df-43c0-9e32-c0dfbff650d2"
    },
    "status": "ok",
    "message": "Faces counted",
    "success": true
}
```

#### `GET /v1/detect` — Detect faces with age/gender/expression

**Parameters:**
- `url` (query, optional, string) — Image URL (or base64/raw body) Example: ``
- `base64` (query, optional, string) — Base64 image data Example: `iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAZElEQVR42u3QQREAAAgDoPUPuhqaw5MHBUjb+SwCBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIEDAfQsbYRN2hzEcHgAAAABJRU5ErkJggg==`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/facedetect-api/v1/detect?url=&base64=iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAZElEQVR42u3QQREAAAgDoPUPuhqaw5MHBUjb%2BSwCBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIEDAfQsbYRN2hzEcHgAAAABJRU5ErkJggg%3D%3D"
```

**Response:**
```json
{
    "data": {
        "count": 0,
        "faces": []
    },
    "meta": {
        "timestamp": "2026-05-31T03:47:41.239Z",
        "request_id": "93c0544a-f4b1-4eda-9e61-ff16bf1874ab"
    },
    "status": "ok",
    "message": "Faces detected",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/facedetect-api
OpenAPI spec: https://www.oanor.com/api/facedetect-api/openapi.json