> ## Documentation Index
> Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Camera faces

> Read where the presenter's face appears in a clip.

Where the presenter's face appears in the finished video, one sample per keyframe of the clip's camera recording (usually 1–2 seconds apart), mapped onto the clip's playback timeline (cuts applied). Use it to keep overlays and text off the presenter's face, or to place them beside it.

Each face is a box as a percentage (0–100) of the video canvas: `xPct` and `yPct` are its top-left corner, `widthPct` and `heightPct` its size. That is the same space as an overlay's `point` and `dimensions`. The box follows the clip's layout at that moment: where the camera sits, its shape and crop, mirroring, and Keep face centered. When the layout crops part of a face, the box covers only the visible part. Read the faces again after changing a clip's layouts.

> [!NOTE]
>
> **All times are milliseconds on the clip's playback timeline** — the video as watched, with cuts applied. It is the same timeline as `get_transcript`, thumbnails, and previews, so nothing needs converting. A start at or past the end of the clip is rejected with a `400`.

## get\_camera\_faces

Get the face samples for a clip. A face holds its place until the next sample. Moments when the layout hides the camera are left out, as are faces the layout crops out and unsure detections (usually a hand or a face in the background). 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 (still processing, or recorded before face detection).

**videoId** `string` *required*

Video ID

**clipId** `string` *required*

Clip ID

**startTimeMs** `integer`

First time to include, in ms on the clip's playback timeline (default: clip start). Must be at least 0.

**endTimeMs** `integer`

First time to exclude, in ms on the clip's playback timeline (default: clip end). Must be greater than `startTimeMs`.


## Related topics

- [List faces in a clip's camera](https://www.tella.com/docs/api-reference/clips/list-faces-in-a-clips-camera.md)
- [Model Context Protocol (MCP)](https://www.tella.com/docs/mcp-server.md)
- [Clips](https://www.tella.com/docs/mcp-tools/clips.md)
- [Update a clip](https://www.tella.com/docs/api-reference/clips/update-a-clip.md)
- [List clips for a video](https://www.tella.com/docs/api-reference/clips/list-clips-for-a-video.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.