--- title: "Update a clip" method: PATCH path: "/v1/videos/{id}/clips/{clipId}" tags: ["Clips"] --- # Update a clip `PATCH /v1/videos/{id}/clips/{clipId}` Update a clip's name, ordering, cuts, background, or transition. At least one field must be provided. ## Path parameters - `id` string, required — Video identifier - `clipId` string, required — Clip identifier ## Request body - UpdateClipRequest — Request body for updating a clip. At least one field must be provided. - `animatedCursor` boolean — Draw an animated cursor from captured mouse data on this clip's screen recording. Returns 400 when the clip has no screen recording. - `background` ClipBackground — 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`, or type = 'gradient' with `gradientColor1`, `gradientColor2`, `gradientAngle`. - `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`. - `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`. Input-only. - `type` 'solid' | 'gradient' | 'image' | 'video', required — Background variant - `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`. - `cuts` Cut[] — Replaces the clip's cuts. Total cut duration must be less than `maxDurationSeconds`. - `durationMs` integer, required — Length of the cut, in milliseconds - `startTimeMs` integer, required — Start of the cut, in ms of the raw recording - `microphoneVolume` number, nullable — Microphone volume for this clip only, overriding the video's `microphoneVolume`. 1 is the recorded level, 0 mutes it, 2 doubles it. Pass null to clear the override so the clip follows the video again. Returns 400 when the clip has no microphone audio to control, i.e. whenever a read reports the field as absent. - `name` string — New clip name - `order` integer — New position of the clip within the video - `studioSound` boolean — Per-clip Studio Sound opt-out. `false` disables enhanced audio for this clip while the video-level switch (see `PATCH /v1/videos/{id}` `studioSound`) stays on; `true` re-enables it. - `systemAudioVolume` number, nullable — System audio (screen or uploaded footage) volume for this clip only, overriding the video's `systemAudioVolume`. Same range and null-to-clear behaviour as `microphoneVolume`. Returns 400 when the clip has no such audio to control, i.e. whenever a read reports the field as absent. - `transition` 'default' | 'smooth' | 'hard_cut' — 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. ## 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`, or type = 'gradient' with `gradientColor1`, `gradientColor2`, `gradientAngle`. - `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`. - `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`. Input-only. - `type` 'solid' | 'gradient' | 'image' | 'video', required — Background variant - `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`. - `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 - `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). - `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. - `429` — You have exceeded the rate limit. Please slow down. - `500` — An unexpected error occurred - `501` — The requested operation is not implemented. --- [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-service-production.skmtc.workers.dev/v1/apis/withchima/tella-public-api/revisions/cd69045c703a/schema)