---
title: "List faces in a clip's camera"
method: GET
path: "/v1/videos/{id}/clips/{clipId}/camera-faces"
tags: ["Clips"]
---

# List faces in a clip's camera

`GET /v1/videos/{id}/clips/{clipId}/camera-faces`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/videos/{id}/clips/{clipId}/camera-faces`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/videos/:id/clips/:clipId/camera-faces/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns where the presenter's face is in the clip's camera recording, one sample per keyframe (usually 1-2 s apart), mapped onto the clip's playback timeline (cuts applied). Boxes are percentages of the camera frame, not of the video canvas: where the camera sits on the canvas depends on the clip's layouts. Keyframes in cut-out footage are dropped. Returns an empty list when the clip has no camera or its recording has no face detections yet. Pass `startTimeMs`/`endTimeMs` to read a window; a window returns the same samples the whole-clip response has in that range.

## Path parameters

- `id` string, required: Video identifier
- `clipId` string, required: Clip identifier

## Query parameters

- `startTimeMs` integer: Only return items at or after this time, in ms on the clip's playback timeline. Defaults to the clip's start.
- `endTimeMs` integer: Only return items before this time (exclusive), in ms on the clip's playback timeline. Must be greater than `startTimeMs`. Defaults to the clip's end. Page through a long clip with windows that meet end to start.

## Response `200`

OK

- ListClipCameraFacesResponse: Faces from the clip's camera recording, placed on the video canvas. Moments when the layout hides the camera are left out. Empty when the clip has no camera or its recording has no detections yet (processing still running, or recorded before face detection)
  - `samples` ClipCameraFaceSample[], required
    - `faces` ClipCameraFace[], required: Every confidently detected face visible on the canvas; empty when none is
      - `heightPct` number, required: Height of the face, as a percentage of the video canvas height
      - `widthPct` number, required: Width of the face, as a percentage of the video canvas width
      - `xPct` number, required: Left edge of the face, as a percentage of the video canvas width
      - `yPct` number, required: Top edge of the face, as a percentage of the video canvas height
    - `timestampMs` number, required: Time on the clip's playback timeline (cuts applied), in ms

## Other responses

- `400`: The request was malformed or contained invalid parameters.
- `401`: Authentication is required. Provide a valid API key.
- `403`: You don't have permission to access this resource.
- `404`: The requested resource was not found.
- `409`: The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles.
- `429`: You have exceeded the rate limit. Please slow down.
- `500`: An unexpected error occurred
- `501`: The requested operation is not implemented.
- `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 72 revisions in range; 1 not diffed.

- **2026-10-15** `12b6eccbb321`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/camera-faces/get.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) - [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/ca74daaf9201?raw)