---
title: "Cut clip ranges by transcript word indices"
method: POST
path: "/v1/videos/{id}/clips/{clipId}/cut-by-transcript"
tags: ["Clips"]
---

# Cut clip ranges by transcript word indices

`POST /v1/videos/{id}/clips/{clipId}/cut-by-transcript`

## Request

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

Cut one or more ranges from a clip by referencing word indices in the transcript. The server reads each word's exact `startTimeMs` / `endTimeMs` and merges the resulting cuts — no padding is applied to word boundaries. Zooms, blurs, highlights and overlays (text, images, media, sound effects) placed entirely on footage the cut removes are deleted with it; clearing the cuts later does not bring them back.

## Path parameters

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

## Request body

- CutClipByTranscriptRequest: Cut one or more ranges from the clip by referencing word indices in the transcript. Indices are stable across cuts (already-cut words are simply absent). The server resolves each range to exact word times and merges the resulting cuts.
  - `wordRanges` TranscriptWordRange[], required: Word ranges to cut. Each range's start and end ms are read directly from the transcript — no padding is applied.
    - `fromWordIndex` integer, required: Index of the first word to cut (inclusive), as reported by the transcript.
    - `toWordIndex` integer, required: Index of the last word to cut (inclusive), as reported by the transcript.

## Response `200`

OK

- GetClipResponse: Response shape for a single clip
  - `clip` Clip, required: A section of a video
    - `animatedCursor` boolean: Whether the clip draws an animated cursor from captured mouse data. Absent when the clip has no screen recording.
    - `background` ClipBackgroundOutput, required: Clip background. Use type = 'solid' with `color`, type = 'image' or 'video' with `sourceId` (from `POST /v1/sources`) or an exact catalog URL from `GET /v1/backgrounds`, type = 'gradient' with `gradientColor1`, `gradientColor2`, `gradientAngle`, type = 'shaderGradient' with `shaderGradientPreset`, or type = 'ambient'.
      - `color` string, nullable: Hex color string. Required when type = 'solid'.
      - `gradientAngle` integer, nullable: Linear gradient angle in degrees. Required when type = 'gradient'.
      - `gradientColor1` string, nullable: Hex color string. Required when type = 'gradient'.
      - `gradientColor2` string, nullable: Hex color string. Required when type = 'gradient'.
      - `imageUrl` string, uri, nullable: Hosted image URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`.
      - `shaderGradientPreset` string, nullable: Animated gradient preset from `GET /v1/backgrounds`. Required when type = 'shaderGradient'.
      - `sourceId` string, nullable: Source ID from `POST /v1/sources` (`kind: image` for type = 'image', `kind: video` for type = 'video'). Required for image/video backgrounds unless using an exact URL from `GET /v1/backgrounds`. A video background source must have its file uploaded, be 20 MB or smaller, and not be an audio or auto capture source; it is also saved to your uploaded video backgrounds, like an upload in the editor. Input-only.
      - `type` 'solid' | 'gradient' | 'image' | 'video' | 'shaderGradient' | 'ambient', required: Background variant. `ambient`: the clip's screen, else its camera, heavily blurred; no other fields. `shaderGradient`: an animated gradient set by `shaderGradientPreset`; echoing a non-preset one unchanged keeps it.
      - `videoDurationSeconds` number, nullable: Video background duration in seconds. Read-only: derived from the uploaded source or catalog entry on input.
      - `videoUrl` string, uri, nullable: Hosted video URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`.
    - `borderStyle` 'none' | 'subtle-shadow' | 'deep-shadow' | 'transparent' | 'solid-shadow-left' | 'solid-shadow-right' | 'snake' | 'glass' | 'custom', required: Border and shadow around the clip's frames — the editor Style panel's Border style. The clip's own value, else the video's. `custom` means the layers were styled one by one or with a retired preset; it can't be written.
    - `cameraCrop` ClipCameraCropOutput: Pixels removed from each edge of the unmirrored camera recording. The edges must leave a visible area.
      - `bottom` number, required: Pixels of the camera recording removed from its bottom edge
      - `left` number, required: Pixels of the camera recording removed from its left edge
      - `right` number, required: Pixels of the camera recording removed from its right edge
      - `top` number, required: Pixels of the camera recording removed from its top edge
    - `cameraFocusPoint` ClipCameraFocusPointOutput: The part of the unmirrored, cropped camera recording kept in view when the camera frame's shape differs from it: 0 keeps the left/top edge, 50 the middle, 100 the right/bottom. The face's position keeps the face in frame.
      - `xPct` number, required: Horizontal position, 0-100
      - `yPct` number, required: Vertical position, 0-100
    - `corners` 'none' | 'regular' | 'squircle', required: Corner rounding of the clip's frames — the editor Style panel's Shape: `none` (square), `regular` (rounded) or `squircle` (very rounded). The clip's own value, else the video's.
    - `createdAt` string, date-time, required: ISO 8601 datetime
    - `cuts` CutOutput[], required: Time ranges cut from the clip's playback
      - `durationMs` integer, required: Length of the cut, in milliseconds
      - `startTimeMs` integer, required: Start of the cut, in ms of the raw recording
    - `durationSeconds` number, required: Effective playback duration of the clip after cuts, in seconds
    - `id` string, required: Unique clip identifier
    - `keepCameraFaceCentered` boolean: Whether Keep face centered is on. Absent without a camera.
    - `layoutSceneType` 'basicSubject' | 'cameraSubject' | 'combi', required: How a clip composes its layers, which determines the set of layouts it accepts: `basicSubject` (screen-only), `cameraSubject` (camera-only), or `combi` (camera + presentation).
    - `maxDurationSeconds` number, required: Total length of the underlying source, in seconds
    - `microphoneVolume` number, nullable: This clip's microphone volume override: a number when the clip overrides the video's `microphoneVolume`, null when it follows it, and absent when the clip has no microphone audio to control — either no such track, or a track whose recording carries no audio (a muted mic, or a screen recording made without sharing system audio).
    - `mirrorCamera` boolean: Whether the clip's camera is mirrored (flipped horizontally). Absent when the clip has no camera.
    - `name` string, required: Clip display name
    - `order` integer, required: Position of the clip within the video
    - `studioSound` boolean, required: Effective Studio Sound (AI audio enhancement) state for this clip: the video-level switch minus this clip's opt-out.
    - `systemAudioVolume` number, nullable: This clip's system audio (screen or uploaded footage) volume override, with the same three states as `microphoneVolume`.
    - `transition` 'default' | 'smooth' | 'hard_cut', required: How a clip enters from the previous one. `default` inherits the video's `defaultClipTransition`; `smooth` and `hard_cut` override it for this clip. The first clip in a video has nothing to transition from.
    - `updatedAt` string, date-time, required: ISO 8601 datetime
    - `videoId` string, required: Video identifier

## 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

> 67 revisions in range; 1 not diffed.

- **2026-10-27** `5caf72ed8935`: 1 info
  - added the optional property `clip/keepCameraFaceCentered` to the response with the `200` status
- **2026-10-15** `12b6eccbb321`: 1 warning, 1 info
  - added the new `ambient` enum value to the `clip/background/type` response property for the response status `200`
  - added the optional property `clip/background/shaderGradientPreset` to the response with the `200` status
- **2026-10-13** `862d32ff02f5`: 3 info
  - added the optional property `clip/cameraCrop` to the response with the `200` status
  - added the optional property `clip/cameraFocusPoint` to the response with the `200` status
  - added the optional property `clip/mirrorCamera` to the response with the `200` status
- **2026-10-09** `25910750ad41`: 1 warning
  - added the new `glass` enum value to the `clip/borderStyle` response property for the response status `200`
- **2026-10-05** `d0e3293b334e`: 1 warning
  - added the new `shaderGradient` enum value to the `clip/background/type` response property for the response status `200`

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/cut-by-transcript/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/668da8c6d5f6?raw)