---
title: "Split a clip in two"
method: POST
path: "/v1/videos/{id}/clips/{clipId}/split"
tags: ["Clips"]
---

# Split a clip in two

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

## Request

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

Split a clip in two at a time on its playback timeline, like the editor's split at the playhead. The clip keeps everything before `atMs`, and a new clip inserted right after it continues from there. Each cut, layout, zoom, blur, highlight and overlay goes to the part it sits on. One that spans `atMs` is split too: each part keeps its side, and a video, audio or sound effect overlay keeps playing in the second clip from where the first stopped. Both parts must play for at least 200 ms. Returns both clips in playback order; the first keeps the original clip's id.

## Path parameters

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

## Request body

- SplitClipRequest: Request body for splitting a clip in two
  - `atMs` integer, required: Where to split, in ms on the clip's playback timeline (cuts applied, the same timeline as the transcript). At least 200 ms from either end of the clip.

## Response `200`

OK

- SplitClipResponse: Response shape for splitting a clip
  - `clips` Clip[], required: The two clips in playback order: the original clip, now ending at the split, and the new clip that continues from it.
    - `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

> 66 revisions in range; 1 not diffed.

- **2026-10-27** `5caf72ed8935`: 1 info
  - added the optional property `clips/items/keepCameraFaceCentered` to the response with the `200` status
- **2026-10-21** `f38f7d23192e`: 1 info
  - endpoint added

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