Skip to main content
POST
/
v1
/
face
/
detect
Detect Face
curl --request POST \
  --url https://api.deepidv.com/v1/face/detect
{
  "faceDetected": true,
  "confidence": 0.99,
  "boundingBox": {
    "top": 0.18,
    "left": 0.31,
    "width": 0.41,
    "height": 0.52
  },
  "landmarks": [
    { "type": "eyeLeft", "x": 0.44, "y": 0.38 },
    { "type": "eyeRight", "x": 0.58, "y": 0.38 },
    { "type": "nose", "x": 0.51, "y": 0.47 },
    { "type": "mouthLeft", "x": 0.46, "y": 0.59 },
    { "type": "mouthRight", "x": 0.57, "y": 0.59 }
  ]
}

POST /v1/face/detect
Submit a single image. If a face is present, the response includes its bounding box, key facial landmarks, and a normalized confidence score. Use this endpoint when you need to confirm a usable face image before sending it to /v1/face/compare or /v1/face/estimate-age — for example, to give the user immediate feedback that their selfie is too dark or off-frame.

​
Request

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key
Content-TypeYesmultipart/form-data or application/json

​
Body parameters

ParameterTypeRequiredDescription
imagebinary | stringYesThe image. For multipart, the file part. For JSON, a base64, base64url, or S3-key string.
See the overview for the shared image rules.

​
Example request

curl -X POST https://api.deepidv.com/v1/face/detect \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image=@selfie.jpg"

​
Response

​
200 — Success

FieldTypeDescription
faceDetectedbooleanTrue when a face was detected
confidencenumber (0–1)Detection confidence for the top face. 0 when no face was detected
boundingBoxobjectNormalized bounding-box coordinates (omitted when no face detected)
landmarksobject[]Facial landmark points (omitted when no face detected)
boundingBox shape: { top, left, width, height }, each normalized to 0–1 against the source image dimensions. landmarks[] shape: { type, x, y }, where type is the landmark name (e.g. eyeLeft, nose, mouthRight) and x/y are normalized to the image dimensions.

​
Error responses

StatusDescription
400Invalid body, unsupported image format, or image larger than 15 MB
401Missing or invalid x-api-key
402Insufficient token balance
403The supplied image S3 key is not readable by this organization
429Rate limit exceeded
500Unexpected server error — safe to retry with backoff
{
  "faceDetected": true,
  "confidence": 0.99,
  "boundingBox": {
    "top": 0.18,
    "left": 0.31,
    "width": 0.41,
    "height": 0.52
  },
  "landmarks": [
    { "type": "eyeLeft", "x": 0.44, "y": 0.38 },
    { "type": "eyeRight", "x": 0.58, "y": 0.38 },
    { "type": "nose", "x": 0.51, "y": 0.47 },
    { "type": "mouthLeft", "x": 0.46, "y": 0.59 },
    { "type": "mouthRight", "x": 0.57, "y": 0.59 }
  ]
}
When no face is detected the endpoint still returns 200 OK with faceDetected: false. Treat that as a UX-level failure (prompt the user to retake) rather than an integration error. Only the highest-confidence face is returned.