---
title: "Detect Faces in Video or Image"
method: POST
path: "/detect_faces"
tags: ["Face Detection"]
---

# Detect Faces in Video or Image

`POST /detect_faces`

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

## Request body

- UnifiedFaceDetectionRequest
  - `url` string, 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.
  - `img` string — 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_frames` integer — Number of frames to extract and analyze (only used for videos, ignored for images)
  - `return_face_url` boolean — 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_face` boolean — 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.
  - `deduplicate` boolean — Whether to enable face deduplication. When set to `false`, all detected faces are returned.

## Response `200`

Face detection completed successfully

- FaceDetectionResponse
  - `error_code` integer, required — Error code (0: success, 1: error)
  - `error_msg` string, required — Error message or success message
  - `faces_obj` object, 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.)

## Other responses

- `400` — Bad request - Invalid input parameters
- `500` — Internal server error

---

[API](https://skmtc.dev/akool/apis/face-detection-api.md) · [All operations](https://skmtc.dev/akool/apis/face-detection-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/akool/face-detection-api/revisions/ce2ff5679949/schema)