API reference

Face APIs

Send an image to Face Detect for geometry only, or to Face Analyze for geometry and visual attributes. The schema on this page is generated from the service’s own models, and the machine-readable version is at /v1/openapi.json if you would rather generate a client.

Authentication

One header, on every request. Create a key in the console; it is shown once and stored only as a peppered hash, so it cannot be shown again.

Authorization: Bearer pd_live_...

Request

POST /v1/face/analyze, with the image as multipart/form-data in an image part. JPEG, PNG or WebP, up to 10 MB and 50 megapixels once decoded.

curl https://pixeldepot.ai/v1/face/analyze \
  -H "Authorization: Bearer pd_live_..." \
  -F "image=@person.jpg"

image_url is not implemented. Fetching a URL a caller supplies is a server-side request forgery surface and wants an allowlist and timeout policy of its own, so sending JSON returns invalid_request rather than a partial version of it.

Response

200, with X-Inference-Duration-Ms giving the milliseconds we spent calling the model. faces may be empty: rare, and still not evidence the frame contains no person.

{
  "request_id": "req_9e3cc8acd17d4087b9b3a593fa4ddd27",
  "image": { "width": 1280, "height": 1920 },
  "faces": [
    {
      "id": "face_1",
      "region": "bounding_box",
      "bounding_box": { "x": 468, "y": 635, "width": 161, "height": 216 },
      "confidence": 0.538,
      "meets_threshold": true,
      "threshold": 0.2,
      "attributes": {
        "estimated_age": {
          "range": "18-64", "estimate": 34, "confidence": 0.957,
          "meets_threshold": true, "threshold": 0.4878,
          "probabilities": [
            { "label": "18-64", "probability": 0.957 },
            { "label": "0-17",  "probability": 0.033 },
            { "label": "65+",   "probability": 0.010 }
          ]
        },
        "perceived_gender_presentation": {
          "label": "Male", "confidence": 0.998,
          "meets_threshold": true, "threshold": 0.5,
          "probabilities": [
            { "label": "Male",   "probability": 0.998 },
            { "label": "Female", "probability": 0.002 }
          ]
        },
        "apparent_ancestry": {
          "label": "White", "confidence": 0.725,
          "meets_threshold": true, "threshold": 0.552,
          "probabilities": [
            { "label": "White", "probability": 0.72 },
            { "label": "Latin", "probability": 0.22 },
            { "label": "Asian", "probability": 0.05 },
            { "label": "Black", "probability": 0.01 }
          ]
        },
        "has_glasses": {
          "label": "no", "confidence": 0.981,
          "meets_threshold": true, "threshold": 0.5215,
          "probabilities": [
            { "label": "no",  "probability": 0.981 },
            { "label": "yes", "probability": 0.019 }
          ]
        }
      }
    }
  ],
  "meta": {
    "models": [
      { "name": "face-detector",   "version": "0.2.0", "weight_sha256": "9511f25a..." },
      { "name": "face-attributes", "version": "0.5.0", "weight_sha256": "e5a96e53..." }
    ],
    "disclosures": [],
    "release_status": "released"
  }
}

Face Detect public beta

POST /v1/face/detectuses the same image limits, but returns only boxes clearing the detector’s fitted 0.90-precision operating point. Results are ordered by confidence. If none qualify, the response is still 200 with faces: []. Up to 50 faces are returned; inspect meta.truncated before treating the array as complete.

curl https://pixeldepot.ai/v1/face/detect \
  -H "Authorization: Bearer pd_live_..." \
  -F "image=@group.jpg"

{
  "request_id": "req_33efc95eea754d68823f6b8e3e30af08",
  "image": { "width": 1600, "height": 900 },
  "faces": [
    {
      "id": "face_1",
      "bounding_box": { "x": 312, "y": 164, "width": 118, "height": 142 },
      "confidence": 0.947,
      "threshold": 0.3681,
      "meets_threshold": true
    }
  ],
  "meta": {
    "models": [
      { "name": "face-detector", "version": "0.2.0", "weight_sha256": "9511f25a..." }
    ],
    "release_status": "released",
    "disclosures": [],
    "max_faces": 50,
    "truncated": false
  }
}

Face Detect keeps operational request metadata and aggregate usage only. PixelDepot does not retain the submitted image or response geometry. Face Analyze images and results remain available to the organization for seven days.

Schema

Generated from the contract. A ? marks an optional field.

What the attributes are measured on

Age, gender presentation and ancestry come from a model trained on web photography, and their accuracy is published per artifact on the model card linked from meta.models.

has_glassesis different and it is worth knowing how. It is trained on 407 hand-labelled crops from one operator’s photo-booth archives and scored out of fold across 402 sessions: accuracy 0.941, recall 0.958, precision 0.767. That is one venue. Performance elsewhere is unmeasured rather than assumed equal, and 72 positives cannot support a subgroup breakdown. The label means lenses in front of the eyes; sunglasses pushed onto the head are no.

It is also the one attribute computed from a second look at the image. Version 0.4.0 read the same whole-face crop as everything else and missed thin wire, rimless and pale frames: at 224×224 with global average pooling, a two-pixel frame does not survive. 0.5.0 classifies the eye band instead, which took recall from 0.889 to 0.958 with no new labels. The cost is one extra forward pass per face, and it is already in the number X-Inference-Duration-Ms reports.

Errors

The error string is part of the contract; the message is not. Match on the code.

What these outputs are not

Estimated age, perceived gender presentation and apparent ancestry are visual classifications of an image. None is a statement about a person’s actual age, gender or ethnicity, none is proof of identity, and none may inform employment, credit, housing, insurance or education decisions. apparent_ancestry must not be used for EU processing. See the Terms and the photograph credits.