---
title: "Cut one or more time ranges from a clip"
method: POST
path: "/v1/videos/{id}/clips/{clipId}/cut"
tags: ["Clips"]
---

# Cut one or more time ranges from a clip

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

## Request

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

Cut one or more time ranges from a clip in a single request. Pass `cuts: [{fromMs, toMs}, ...]` for multiple ranges or the legacy `fromMs`/`toMs` pair for a single range. Overlapping or adjacent ranges are merged into the clip's existing cuts. 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. To clear all cuts, call updateClip with cuts: [].

## Path parameters

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

## Request body

- CutClipRequest: Cut one or more time ranges from the clip in a single request. Provide either `cuts: [{fromMs, toMs}, ...]` (preferred) or the legacy single-range `fromMs`/`toMs` pair. Overlapping or adjacent ranges are merged into the clip's existing cuts.
  - `cuts` CutRange[]: Time ranges to cut from the clip. Merged with the clip's existing cuts; overlapping or adjacent ranges are joined.
    - `fromMs` integer, required: Start of the range to cut, in ms on the clip's playback timeline.
    - `toMs` integer, required: End of the range to cut, in ms on the clip's playback timeline. Clamped to the clip's playable duration.
  - `fromMs` integer: Single-range shortcut for `cuts: [{fromMs, toMs}]`. Use `cuts` for multiple ranges.
  - `toMs` integer: Single-range shortcut for `cuts: [{fromMs, toMs}]`. Use `cuts` for multiple ranges.

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

> 72 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/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)