Sign in

v1

latestOpenAPI 3.0.32026-07-26214565.6 KB
Face Detection

Detect Faces in Video or Image

Unified endpoint to detect faces in either video or image from URL or base64-encoded image data.

This endpoint:

  1. Auto-detects media type (video/image) based on URL
  2. Downloads media from the provided URL asynchronously (or decodes base64 image)
  3. Processes media (extracts frames for video, loads image for image)
  4. Detects faces using InsightFace with face tracking for videos
  5. Returns bounding boxes and 6-point landmarks for each detected face
  6. For videos, tracks faces across frames and marks previous positions as removed
  7. Optionally returns cropped face image URLs (when return_face_url=true)
  8. Optionally returns only the largest face (when single_face=true)

Input Modes:

  • URL mode: provide url parameter with image/video URL
  • Base64 mode: provide img parameter with base64-encoded image data
  • If both are provided, url takes priority
post/detect_faces

Request body

urlstring uri

URL of the video or image to process. The media type will be auto-detected based on the file extension. Either url or img must be provided. If both are provided, url takes priority.

imgstring

Base64-encoded image data. Supports both plain base64 string and data URI format (e.g., "data:image/jpeg;base64,..."). Either url or img must be provided. If both are provided, url takes priority.

num_framesinteger

Number of frames to extract and analyze (only used for videos, ignored for images)

return_face_urlboolean

Whether to return cropped face image URLs. When set to true, the response will include:

  • face_urls: URLs of cropped face images
  • crop_region: The region used for cropping in original image coordinates
  • crop_landmarks: Landmarks relative to the cropped image
single_faceboolean

When set to true, only returns the largest face (by area) in each frame. Useful when you only need the main/primary face in the image or video.

deduplicateboolean

Whether to enable face deduplication. When set to false, all detected faces are returned.

Example request

{
  "url": "https://example.com/media.mp4",
  "img": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "num_frames": 5,
  "deduplicate": true
}

Response

Face detection completed successfully

error_codeinteger required

Error code (0: success, 1: error)

error_msgstring required

Error message or success message

faces_objobject required

Dictionary of face detection results keyed by frame index (as string). For images, only frame "0" will be present. For videos, multiple frames will be present (e.g., "0", "5", "10", etc.)

Example response

{
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [
        [
          [
            120,
            85
          ],
          [
            180,
            88
          ],
          [
            150,
            130
          ],
          [
            150,
            165
          ],
          [
            125,
            165
          ],
          [
            175,
            168
          ]
        ]
      ],
      "landmarks_str": [
        "120,85:180,88:150,130:150,165"
      ],
      "region": [
        [
          80,
          50,
          150,
          180
        ]
      ],
      "removed": [],
      "frame_time": null,
      "face_urls": null,
      "crop_region": null,
      "crop_landmarks": null
    }
  }
}