---
title: "Add a highlight to a clip"
method: POST
path: "/v1/videos/{id}/clips/{clipId}/highlights"
tags: ["Clips"]
---

# Add a highlight to a clip

`POST /v1/videos/{id}/clips/{clipId}/highlights`

## Request

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

Adds a highlight mask to a clip. Targets the footage in the clip's Screen slot at startTimeMs: the screen recording, or b-roll media a layout puts there.

## Path parameters

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

## Request body

- AddClipMaskRequest: Add a blur or highlight mask. Targets the footage in the clip's Screen slot at startTimeMs: the screen recording, or b-roll media a layout puts there. Times are in ms on the clip's playback timeline (cuts applied).
  - `dimensions` MaskDimensions, required: Size of the masked rectangle (percentages)
    - `heightPct` number, required
    - `widthPct` number, required
  - `durationMs` integer, required
  - `intensity` number: Strength from 0 to 1. Blur: 0 is the standard blur and 1 blurs three times as heavily; the content stays fully hidden at every value (defaults to 0). Highlight: how dark the area outside the highlight goes, 0 = no dimming, 1 = black (defaults to 0.7).
  - `point` MaskPoint, required: Top-left corner of the masked rectangle (percentages)
    - `xPct` number, required
    - `yPct` number, required
  - `startTimeMs` integer, required: Start time in ms on the clip's playback timeline (cuts applied)
  - `transition` 'smooth' | 'hard_cut': How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly.

## Response `200`

OK

- ClipMaskResponse: A mask on a clip
  - `mask` ClipMask, required: A blur or highlight mask on a clip. Times are in ms on the clip's playback timeline (cuts applied). Internally the mask stays anchored to the footage, so it doesn't drift when cuts change later.
    - `dimensions` MaskDimensionsOutput, required: Size of the masked rectangle (percentages)
      - `heightPct` number, required
      - `widthPct` number, required
    - `durationMs` number, required
    - `id` string, required: Mask ID
    - `intensity` number, required: Strength from 0 to 1. Blur: 0 is the standard blur and 1 blurs three times as heavily; the content stays fully hidden at every value (defaults to 0). Highlight: how dark the area outside the highlight goes, 0 = no dimming, 1 = black (defaults to 0.7).
    - `point` MaskPointOutput, required: Top-left corner of the masked rectangle (percentages)
      - `xPct` number, required
      - `yPct` number, required
    - `startTimeMs` number, required: Start time in ms on the clip's playback timeline (cuts applied)
    - `transition` 'smooth' | 'hard_cut', required: How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly.
    - `type` 'blur' | 'highlight', required

## 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-23** `f7923c831a59`: 2 info
  - added the new optional request property `transition`
  - added the required property `mask/transition` to the response with the `200` status
- **2026-09-28** `ac47c99c144f`: 9 warning
  - added the new `edit_conflict` enum value to the `error` response property for the response status `400`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `401`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `403`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `404`
  - …5 more
- **2026-09-13** `8755ac4e46ca`: 2 info
  - added the new optional request property `intensity`
  - added the required property `mask/intensity` to the response with the `200` status
- **2026-09-09** `6b1132ef42fb`: 14 warning, 2 info
  - added the new `conflict` enum value to the `error` response property for the response status `400`
  - added the new `conflict` enum value to the `error` response property for the response status `401`
  - added the new `conflict` enum value to the `error` response property for the response status `403`
  - added the new `conflict` enum value to the `error` response property for the response status `404`
  - …12 more

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/highlights/post.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)