> ## 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. # List faces in a clip's camera > 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. ## OpenAPI ````yaml /openapi.json get /v1/videos/{id}/clips/{clipId}/camera-faces openapi: 3.0.3 info: description: >- The Tella Public API allows you to programmatically access your videos and playlists, including transcripts, chapters, and thumbnails. ## Authentication All requests require a Bearer token in the Authorization header: ``` Authorization: Bearer tella_pk_xxxxx... ``` API keys can be generated in your Tella workspace settings. ## Rate Limiting The API is rate-limited to 100 requests per minute per user within a workspace. Rate limit information is returned in response headers: - `RateLimit-Policy`: Named quota, request limit, and window in seconds - `RateLimit`: Remaining quota and seconds until reset - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp in milliseconds when the window resets A `429 Too Many Requests` response also includes `Retry-After` in seconds. title: Tella Public API version: 1.0.0 servers: - description: Production url: https://api.tella.com security: [] tags: - description: Video operations name: Videos - description: Sections of a video name: Clips - description: Playlist operations name: Playlists - description: Sidebar groups for organizing playlists name: Playlist Groups - description: Tags for categorizing and filtering videos name: Tags - description: >- Viewing analytics for a video or across the workspace: plays, watch time, retention, geography, referrers name: Analytics - description: Personal, workspace, and default video backgrounds name: Backgrounds - description: >- Reusable media saved to a workspace, plus Tella's curated sound effect and background music catalogs — the same items the editor's media panels show name: Library - description: Webhook endpoint management name: Webhooks externalDocs: description: API versioning and deprecation policy url: https://www.tella.com/docs/versioning paths: /v1/videos/{id}/clips/{clipId}/camera-faces: get: tags: - Clips summary: List faces in a clip's camera description: >- 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. operationId: listClipCameraFaces parameters: - description: Video identifier in: path name: id required: true schema: description: Video identifier example: vid_abc123def456 type: string - description: Clip identifier in: path name: clipId required: true schema: description: Clip identifier example: cl_xyz789ghi012 type: string - description: >- Only return items at or after this time, in ms on the clip's playback timeline. Defaults to the clip's start. in: query name: startTimeMs schema: description: >- Only return items at or after this time, in ms on the clip's playback timeline. Defaults to the clip's start. example: 60000 maximum: 9007199254740991 minimum: 0 type: integer - description: >- 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. in: query name: endTimeMs schema: description: >- 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. example: 120000 maximum: 9007199254740991 minimum: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListClipCameraFacesResponse' description: OK headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '400': content: application/json: example: docsUrl: https://docs.tella.com/ error: bad_request message: The request was malformed or contained invalid parameters. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was malformed or contained invalid parameters. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '401': content: application/json: example: docsUrl: https://docs.tella.com/ error: unauthorized message: Authentication is required. Provide a valid API key. schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication is required. Provide a valid API key. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '403': content: application/json: example: docsUrl: https://docs.tella.com/ error: forbidden message: You don't have permission to access this resource. schema: $ref: '#/components/schemas/ErrorResponse' description: You don't have permission to access this resource. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '404': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_found message: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '409': content: application/json: example: docsUrl: https://docs.tella.com/ error: conflict message: >- 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. schema: $ref: '#/components/schemas/ErrorResponse' description: >- 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. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '429': content: application/json: example: docsUrl: https://docs.tella.com/ error: rate_limited message: You have exceeded the rate limit. Please slow down. schema: $ref: '#/components/schemas/ErrorResponse' description: You have exceeded the rate limit. Please slow down. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Retry-After: $ref: '#/components/headers/RetryAfter' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '500': content: application/json: example: docsUrl: https://docs.tella.com/ error: server_error message: An unexpected error occurred schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error occurred headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '501': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_implemented message: The requested operation is not implemented. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested operation is not implemented. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '503': content: application/json: example: docsUrl: https://docs.tella.com/ error: unavailable message: >- A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. schema: $ref: '#/components/schemas/ErrorResponse' description: >- A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' security: - BearerAuth: [] components: schemas: ListClipCameraFacesResponse: additionalProperties: false description: >- 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) properties: samples: items: $ref: '#/components/schemas/ClipCameraFaceSample' type: array required: - samples type: object ErrorResponse: additionalProperties: false description: Standard error response format properties: docsUrl: description: Link to Tella API documentation example: https://docs.tella.com/ format: uri type: string error: description: Machine-readable error code enum: - bad_request - unauthorized - forbidden - not_found - rate_limited - server_error - conflict - edit_conflict - not_implemented - unavailable example: not_found type: string message: description: Human-readable error message example: Resource not found type: string required: - error - message - docsUrl type: object ClipCameraFaceSample: additionalProperties: false description: >- The faces in one keyframe of the clip's camera recording, while the camera is on screen. Keyframes are usually 1-2 s apart; a face holds its place until the next sample properties: faces: description: >- Every confidently detected face visible on the canvas; empty when none is items: $ref: '#/components/schemas/ClipCameraFace' type: array timestampMs: description: Time on the clip's playback timeline (cuts applied), in ms type: number required: - timestampMs - faces type: object ClipCameraFace: additionalProperties: false description: >- Where a face appears in the finished video, in the same space as an overlay's `point`/`dimensions`. Only the visible part of a face the layout partly crops properties: heightPct: description: Height of the face, as a percentage of the video canvas height maximum: 100 minimum: 0 type: number widthPct: description: Width of the face, as a percentage of the video canvas width maximum: 100 minimum: 0 type: number xPct: description: Left edge of the face, as a percentage of the video canvas width maximum: 100 minimum: 0 type: number yPct: description: Top edge of the face, as a percentage of the video canvas height maximum: 100 minimum: 0 type: number required: - xPct - yPct - widthPct - heightPct type: object headers: Deprecation: description: Indicates that an API operation is deprecated, following RFC 9745 example: '@1767225600' schema: type: string RateLimit: description: >- Current quota with remaining requests (`r`) and seconds until reset (`t`) example: '"public-api";r=95;t=42' schema: type: string RateLimitPolicy: description: >- Named quota policy with the request limit (`q`) and window in seconds (`w`) example: '"public-api";q=100;w=60' schema: type: string Sunset: description: >- Indicates when a deprecated API operation will become unavailable, following RFC 8594 example: Tue, 30 Jun 2026 23:59:59 GMT schema: type: string XRateLimitLimit: description: Maximum requests allowed in the current window example: 100 schema: type: integer XRateLimitRemaining: description: Requests remaining in the current window example: 95 schema: type: integer XRateLimitReset: description: Unix timestamp in milliseconds when the window resets example: 1704067200000 schema: format: int64 type: integer RetryAfter: description: Seconds to wait before retrying a rate-limited request example: 45 schema: minimum: 1 type: integer securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ```` ## Related topics - [Camera faces](/docs/mcp-tools/camera-faces.md) - [Can I record with multiple cameras?](/docs/help/faq/multiple-cameras.md) - [List layouts on a clip](/docs/api-reference/clips/list-layouts-on-a-clip.md) - [Clips](/docs/mcp-tools/clips.md) - [List clips for a video](/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.