---
title: "Detect faces in video"
method: POST
path: "/face-detect"
tags: ["Face Detection"]
---

# Detect faces in video

`POST /face-detect`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/face-detect`
- Auth: HTTP bearer

Analyze video to detect all faces

## Request body

- FaceDetectionRequest
  - `url` string, required: URL of the target video to analyze
  - `frame_extraction_id` string, uuid: Optional: Use previously extracted frames
  - `frame_extraction_config` FrameExtractionConfig: Configuration for frame extraction. Currently only supports uniform strategy.
    - `strategy` 'uniform', required: Frame extraction strategy - currently only 'uniform' is supported
    - `uniform_config` FrameExtractionUniformConfig: Configuration for uniform frame extraction
      - `frames_per_second` number: Number of frames to extract per second of video
      - `max_width` number: Maximum width of extracted frames in pixels. Aspect ratio is preserved.
    - `thumbnails_config` FrameExtractionThumbnailsConfig: Configuration for frame thumbnails
      - `enable_frame_thumbnails` boolean: Whether to generate CDN-hosted thumbnails for extracted frames
    - `start_time_seconds` number: Optional: The start time of the video in seconds to start extracting frames from
    - `end_time_seconds` number: Optional: The end time of the video in seconds to stop extracting frames at

## Response `200`

Face detection job created successfully

- FaceDetection
  - `face_detection_id` string, uuid, required: Unique identifier for the face detection job
  - `frame_extraction_id` string, uuid: ID of the frame extraction used
  - `file_id` string, uuid: ID of the target file
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required: Status of the face detection job
  - `created_at` number, required: Unix timestamp in milliseconds when the job was created
  - `data` object: Face detection results (only present when status is completed)
    - `object` 'list': Object type, always 'list'
    - `total` integer: Total number of faces detected
    - `limit` integer: Number of faces returned per page
    - `offset` integer: Offset from the start of the faces list
    - `faces` DetectedFace[]: Array of detected faces
      - `id` string, uuid, required: Unique identifier for the detected face
      - `face_bounding_box` FaceBoundingBox, required
        - `height` number, required: Height of the bounding box (normalized 0-1)
        - `width` number, required: Width of the bounding box (normalized 0-1)
        - `top` number, required: Top position of the bounding box (normalized 0-1)
        - `left` number, required: Left position of the bounding box (normalized 0-1)
      - `frame_id` string, uuid, required: ID of the frame where the face was detected
      - `timestamp` number, required: Timestamp of the frame in seconds
      - `thumbnail_url` string: URL of the frame thumbnail (if frame extraction enabled thumbnails)

## Other responses

- `400`: Invalid request parameters or configuration
- `403`: Usage limit reached (monthly face detection jobs, or the file limits when given a new URL) — `code: usage_limit_reached`
- `404`: Target video file not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 5 info
  - added the non-success response with the status `403`
  - removed the non-success response with the status `429`
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `404` status
  - …1 more
- **2026-03-11** `1d5d6115c0d0`: 3 info
  - the `enable_frame_thumbnails` request property default value `true` was removed
  - the `frames_per_second` request property default value `1` was removed
  - the `max_width` request property default value `1024` was removed
- **2025-10-16** `e2dce1715ffc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/face-detect/post.md)

---

[API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)