Update a clip

curl --request PATCH \
  --url https://api.tella.com/v1/videos/{id}/clips/{clipId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "animatedCursor": true,
  "borderStyle": "subtle-shadow",
  "cameraCrop": {
    "bottom": 1,
    "left": 1,
    "right": 1,
    "top": 1
  },
  "cameraFocusPoint": {
    "xPct": 50,
    "yPct": 35
  },
  "corners": "squircle",
  "cuts": [
    {
      "durationMs": 750,
      "startTimeMs": 1500
    }
  ],
  "microphoneVolume": 0.4,
  "mirrorCamera": true,
  "name": "Updated intro",
  "order": 2,
  "studioSound": false,
  "systemAudioVolume": 1.5,
  "transition": "default"
}
'

import requests

url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}"

payload = {
    "animatedCursor": True,
    "borderStyle": "subtle-shadow",
    "cameraCrop": {
        "bottom": 1,
        "left": 1,
        "right": 1,
        "top": 1
    },
    "cameraFocusPoint": {
        "xPct": 50,
        "yPct": 35
    },
    "corners": "squircle",
    "cuts": [
        {
            "durationMs": 750,
            "startTimeMs": 1500
        }
    ],
    "microphoneVolume": 0.4,
    "mirrorCamera": True,
    "name": "Updated intro",
    "order": 2,
    "studioSound": False,
    "systemAudioVolume": 1.5,
    "transition": "default"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    animatedCursor: true,
    borderStyle: 'subtle-shadow',
    cameraCrop: {bottom: 1, left: 1, right: 1, top: 1},
    cameraFocusPoint: {xPct: 50, yPct: 35},
    corners: 'squircle',
    cuts: [{durationMs: 750, startTimeMs: 1500}],
    microphoneVolume: 0.4,
    mirrorCamera: true,
    name: 'Updated intro',
    order: 2,
    studioSound: false,
    systemAudioVolume: 1.5,
    transition: 'default'
  })
};

fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tella.com/v1/videos/{id}/clips/{clipId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'animatedCursor' => true,
    'borderStyle' => 'subtle-shadow',
    'cameraCrop' => [
        'bottom' => 1,
        'left' => 1,
        'right' => 1,
        'top' => 1
    ],
    'cameraFocusPoint' => [
        'xPct' => 50,
        'yPct' => 35
    ],
    'corners' => 'squircle',
    'cuts' => [
        [
                'durationMs' => 750,
                'startTimeMs' => 1500
        ]
    ],
    'microphoneVolume' => 0.4,
    'mirrorCamera' => true,
    'name' => 'Updated intro',
    'order' => 2,
    'studioSound' => false,
    'systemAudioVolume' => 1.5,
    'transition' => 'default'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tella.com/v1/videos/{id}/clips/{clipId}"

	payload := strings.NewReader("{\n  \"animatedCursor\": true,\n  \"borderStyle\": \"subtle-shadow\",\n  \"cameraCrop\": {\n    \"bottom\": 1,\n    \"left\": 1,\n    \"right\": 1,\n    \"top\": 1\n  },\n  \"cameraFocusPoint\": {\n    \"xPct\": 50,\n    \"yPct\": 35\n  },\n  \"corners\": \"squircle\",\n  \"cuts\": [\n    {\n      \"durationMs\": 750,\n      \"startTimeMs\": 1500\n    }\n  ],\n  \"microphoneVolume\": 0.4,\n  \"mirrorCamera\": true,\n  \"name\": \"Updated intro\",\n  \"order\": 2,\n  \"studioSound\": false,\n  \"systemAudioVolume\": 1.5,\n  \"transition\": \"default\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.tella.com/v1/videos/{id}/clips/{clipId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"animatedCursor\": true,\n  \"borderStyle\": \"subtle-shadow\",\n  \"cameraCrop\": {\n    \"bottom\": 1,\n    \"left\": 1,\n    \"right\": 1,\n    \"top\": 1\n  },\n  \"cameraFocusPoint\": {\n    \"xPct\": 50,\n    \"yPct\": 35\n  },\n  \"corners\": \"squircle\",\n  \"cuts\": [\n    {\n      \"durationMs\": 750,\n      \"startTimeMs\": 1500\n    }\n  ],\n  \"microphoneVolume\": 0.4,\n  \"mirrorCamera\": true,\n  \"name\": \"Updated intro\",\n  \"order\": 2,\n  \"studioSound\": false,\n  \"systemAudioVolume\": 1.5,\n  \"transition\": \"default\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"animatedCursor\": true,\n  \"borderStyle\": \"subtle-shadow\",\n  \"cameraCrop\": {\n    \"bottom\": 1,\n    \"left\": 1,\n    \"right\": 1,\n    \"top\": 1\n  },\n  \"cameraFocusPoint\": {\n    \"xPct\": 50,\n    \"yPct\": 35\n  },\n  \"corners\": \"squircle\",\n  \"cuts\": [\n    {\n      \"durationMs\": 750,\n      \"startTimeMs\": 1500\n    }\n  ],\n  \"microphoneVolume\": 0.4,\n  \"mirrorCamera\": true,\n  \"name\": \"Updated intro\",\n  \"order\": 2,\n  \"studioSound\": false,\n  \"systemAudioVolume\": 1.5,\n  \"transition\": \"default\"\n}"

response = http.request(request)
puts response.read_body

{
  "clip": {
    "background": {
      "type": "solid",
      "color": "#000000ff",
      "gradientAngle": 45,
      "gradientColor1": "#ff0080ff",
      "gradientColor2": "#7928caff",
      "imageUrl": "<string>",
      "shaderGradientPreset": "Halo",
      "sourceId": "su_abc123",
      "videoDurationSeconds": 12.4,
      "videoUrl": "<string>"
    },
    "borderStyle": "subtle-shadow",
    "corners": "regular",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "cuts": [
      {
        "durationMs": 750,
        "startTimeMs": 1500
      }
    ],
    "durationSeconds": 12.5,
    "id": "cl_xyz789ghi012",
    "layoutSceneType": "combi",
    "maxDurationSeconds": 14.2,
    "name": "Intro",
    "order": 0,
    "studioSound": false,
    "transition": "default",
    "updatedAt": "2026-01-15T14:45:00.000Z",
    "videoId": "vid_abc123def456",
    "animatedCursor": true,
    "cameraCrop": {
      "bottom": 1,
      "left": 1,
      "right": 1,
      "top": 1
    },
    "cameraFocusPoint": {
      "xPct": 50,
      "yPct": 35
    },
    "microphoneVolume": 0.4,
    "mirrorCamera": false,
    "systemAudioVolume": null
  }
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "bad_request",
  "message": "The request was malformed or contained invalid parameters."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "unauthorized",
  "message": "Authentication is required. Provide a valid API key."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "forbidden",
  "message": "You don't have permission to access this resource."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "not_found",
  "message": "The requested resource was not found."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "conflict",
  "message": "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."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "rate_limited",
  "message": "You have exceeded the rate limit. Please slow down."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "server_error",
  "message": "An unexpected error occurred"
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "not_implemented",
  "message": "The requested operation is not implemented."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "unavailable",
  "message": "A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay."
}

PATCH

https://api.tella.com

videos

{id}

clips

{clipId}

Update a clip

curl --request PATCH \
  --url https://api.tella.com/v1/videos/{id}/clips/{clipId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "animatedCursor": true,
  "borderStyle": "subtle-shadow",
  "cameraCrop": {
    "bottom": 1,
    "left": 1,
    "right": 1,
    "top": 1
  },
  "cameraFocusPoint": {
    "xPct": 50,
    "yPct": 35
  },
  "corners": "squircle",
  "cuts": [
    {
      "durationMs": 750,
      "startTimeMs": 1500
    }
  ],
  "microphoneVolume": 0.4,
  "mirrorCamera": true,
  "name": "Updated intro",
  "order": 2,
  "studioSound": false,
  "systemAudioVolume": 1.5,
  "transition": "default"
}
'

import requests

url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}"

payload = {
    "animatedCursor": True,
    "borderStyle": "subtle-shadow",
    "cameraCrop": {
        "bottom": 1,
        "left": 1,
        "right": 1,
        "top": 1
    },
    "cameraFocusPoint": {
        "xPct": 50,
        "yPct": 35
    },
    "corners": "squircle",
    "cuts": [
        {
            "durationMs": 750,
            "startTimeMs": 1500
        }
    ],
    "microphoneVolume": 0.4,
    "mirrorCamera": True,
    "name": "Updated intro",
    "order": 2,
    "studioSound": False,
    "systemAudioVolume": 1.5,
    "transition": "default"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    animatedCursor: true,
    borderStyle: 'subtle-shadow',
    cameraCrop: {bottom: 1, left: 1, right: 1, top: 1},
    cameraFocusPoint: {xPct: 50, yPct: 35},
    corners: 'squircle',
    cuts: [{durationMs: 750, startTimeMs: 1500}],
    microphoneVolume: 0.4,
    mirrorCamera: true,
    name: 'Updated intro',
    order: 2,
    studioSound: false,
    systemAudioVolume: 1.5,
    transition: 'default'
  })
};

fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tella.com/v1/videos/{id}/clips/{clipId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'animatedCursor' => true,
    'borderStyle' => 'subtle-shadow',
    'cameraCrop' => [
        'bottom' => 1,
        'left' => 1,
        'right' => 1,
        'top' => 1
    ],
    'cameraFocusPoint' => [
        'xPct' => 50,
        'yPct' => 35
    ],
    'corners' => 'squircle',
    'cuts' => [
        [
                'durationMs' => 750,
                'startTimeMs' => 1500
        ]
    ],
    'microphoneVolume' => 0.4,
    'mirrorCamera' => true,
    'name' => 'Updated intro',
    'order' => 2,
    'studioSound' => false,
    'systemAudioVolume' => 1.5,
    'transition' => 'default'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tella.com/v1/videos/{id}/clips/{clipId}"

	payload := strings.NewReader("{\n  \"animatedCursor\": true,\n  \"borderStyle\": \"subtle-shadow\",\n  \"cameraCrop\": {\n    \"bottom\": 1,\n    \"left\": 1,\n    \"right\": 1,\n    \"top\": 1\n  },\n  \"cameraFocusPoint\": {\n    \"xPct\": 50,\n    \"yPct\": 35\n  },\n  \"corners\": \"squircle\",\n  \"cuts\": [\n    {\n      \"durationMs\": 750,\n      \"startTimeMs\": 1500\n    }\n  ],\n  \"microphoneVolume\": 0.4,\n  \"mirrorCamera\": true,\n  \"name\": \"Updated intro\",\n  \"order\": 2,\n  \"studioSound\": false,\n  \"systemAudioVolume\": 1.5,\n  \"transition\": \"default\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.tella.com/v1/videos/{id}/clips/{clipId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"animatedCursor\": true,\n  \"borderStyle\": \"subtle-shadow\",\n  \"cameraCrop\": {\n    \"bottom\": 1,\n    \"left\": 1,\n    \"right\": 1,\n    \"top\": 1\n  },\n  \"cameraFocusPoint\": {\n    \"xPct\": 50,\n    \"yPct\": 35\n  },\n  \"corners\": \"squircle\",\n  \"cuts\": [\n    {\n      \"durationMs\": 750,\n      \"startTimeMs\": 1500\n    }\n  ],\n  \"microphoneVolume\": 0.4,\n  \"mirrorCamera\": true,\n  \"name\": \"Updated intro\",\n  \"order\": 2,\n  \"studioSound\": false,\n  \"systemAudioVolume\": 1.5,\n  \"transition\": \"default\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"animatedCursor\": true,\n  \"borderStyle\": \"subtle-shadow\",\n  \"cameraCrop\": {\n    \"bottom\": 1,\n    \"left\": 1,\n    \"right\": 1,\n    \"top\": 1\n  },\n  \"cameraFocusPoint\": {\n    \"xPct\": 50,\n    \"yPct\": 35\n  },\n  \"corners\": \"squircle\",\n  \"cuts\": [\n    {\n      \"durationMs\": 750,\n      \"startTimeMs\": 1500\n    }\n  ],\n  \"microphoneVolume\": 0.4,\n  \"mirrorCamera\": true,\n  \"name\": \"Updated intro\",\n  \"order\": 2,\n  \"studioSound\": false,\n  \"systemAudioVolume\": 1.5,\n  \"transition\": \"default\"\n}"

response = http.request(request)
puts response.read_body

{
  "clip": {
    "background": {
      "type": "solid",
      "color": "#000000ff",
      "gradientAngle": 45,
      "gradientColor1": "#ff0080ff",
      "gradientColor2": "#7928caff",
      "imageUrl": "<string>",
      "shaderGradientPreset": "Halo",
      "sourceId": "su_abc123",
      "videoDurationSeconds": 12.4,
      "videoUrl": "<string>"
    },
    "borderStyle": "subtle-shadow",
    "corners": "regular",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "cuts": [
      {
        "durationMs": 750,
        "startTimeMs": 1500
      }
    ],
    "durationSeconds": 12.5,
    "id": "cl_xyz789ghi012",
    "layoutSceneType": "combi",
    "maxDurationSeconds": 14.2,
    "name": "Intro",
    "order": 0,
    "studioSound": false,
    "transition": "default",
    "updatedAt": "2026-01-15T14:45:00.000Z",
    "videoId": "vid_abc123def456",
    "animatedCursor": true,
    "cameraCrop": {
      "bottom": 1,
      "left": 1,
      "right": 1,
      "top": 1
    },
    "cameraFocusPoint": {
      "xPct": 50,
      "yPct": 35
    },
    "microphoneVolume": 0.4,
    "mirrorCamera": false,
    "systemAudioVolume": null
  }
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "bad_request",
  "message": "The request was malformed or contained invalid parameters."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "unauthorized",
  "message": "Authentication is required. Provide a valid API key."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "forbidden",
  "message": "You don't have permission to access this resource."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "not_found",
  "message": "The requested resource was not found."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "conflict",
  "message": "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."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "rate_limited",
  "message": "You have exceeded the rate limit. Please slow down."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "server_error",
  "message": "An unexpected error occurred"
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "not_implemented",
  "message": "The requested operation is not implemented."
}

{
  "docsUrl": "https://docs.tella.com/",
  "error": "unavailable",
  "message": "A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay."
}

Authorizations

Authorization

string

header

required

API key obtained from your Tella account settings

Path Parameters

string

required

Video identifier

Example:

"vid_abc123def456"

clipId

string

required

Clip identifier

Example:

"cl_xyz789ghi012"

Body

application/json

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.

Example:

true

background

object

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'.

Hide child attributes

background.type

enum<string>

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.

Available options:

solid,

gradient,

image,

video,

shaderGradient,

ambient

Example:

"solid"

background.color

string | null

Hex color string. Required when type = 'solid'.

Example:

"#000000ff"

background.gradientAngle

integer | null

Linear gradient angle in degrees. Required when type = 'gradient'.

Required range: -9007199254740991 <= x <= 9007199254740991

Example:

45

background.gradientColor1

string | null

Hex color string. Required when type = 'gradient'.

Example:

"#ff0080ff"

background.gradientColor2

string | null

Hex color string. Required when type = 'gradient'.

Example:

"#7928caff"

background.imageUrl

string<uri> | null

Hosted image URL. Present in responses and accepted as input only when copied exactly from GET /v1/backgrounds; otherwise pass sourceId.

background.shaderGradientPreset

string | null

Animated gradient preset from GET /v1/backgrounds. Required when type = 'shaderGradient'.

Example:

"Halo"

background.sourceId

string | null

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.

Example:

"su_abc123"

background.videoDurationSeconds

number | null

Video background duration in seconds. Read-only: derived from the uploaded source or catalog entry on input.

Required range: x >= 0

Example:

12.4

background.videoUrl

string<uri> | null

Hosted video URL. Present in responses and accepted as input only when copied exactly from GET /v1/backgrounds; otherwise pass sourceId.

borderStyle

enum<string>

Border and shadow around the clip's frames — the editor Style panel's Border style. solid-shadow-left and solid-shadow-right are the solid shadow and its direction; snake and glass (a liquid glass rim) keep the clip's current settings for that style, else the editor's default. Applies to this clip only, across all of its layouts.

Available options:

none,

subtle-shadow,

deep-shadow,

transparent,

solid-shadow-left,

solid-shadow-right,

snake,

glass

Example:

"subtle-shadow"

cameraCrop

object | null

Crop the camera across every layout of this clip, like the editor's camera crop on "All layouts in this clip": per-layout camera crops are dropped, masks on the camera stay on their content and custom layouts keep the camera's on-canvas scale. null removes the crop. Returns 400 when the clip has no camera.

Hide child attributes

cameraCrop.bottom

number

required

Pixels of the camera recording removed from its bottom edge

Required range: x >= 0

cameraCrop.left

number

required

Pixels of the camera recording removed from its left edge

Required range: x >= 0

cameraCrop.right

number

required

Pixels of the camera recording removed from its right edge

Required range: x >= 0

cameraCrop.top

number

required

Pixels of the camera recording removed from its top edge

Required range: x >= 0

cameraFocusPoint

object | null

Reframe the camera across every layout of this clip, like the editor's Crop → Adjust camera on "All layouts in this clip": per-layout focus points are dropped. null resets it to the middle. The layout and the camera frame's position and size don't change. Returns 400 when the clip has no camera.

Hide child attributes

cameraFocusPoint.xPct

number

required

Horizontal position, 0-100

Required range: 0 <= x <= 100

cameraFocusPoint.yPct

number

required

Vertical position, 0-100

Required range: 0 <= x <= 100

Example:

{ "xPct": 50, "yPct": 35 }

corners

enum<string>

Corner rounding of the clip's frames (screen and camera) — the editor Style panel's Shape: none (square), regular (rounded) or squircle (very rounded). Applies to this clip only, like the editor's "Apply to this clip only", across all of its layouts. A circle camera stays a circle.

Available options:

none,

regular,

squircle

Example:

"squircle"

cuts

object[]

Replaces the clip's cuts. Total cut duration must be less than maxDurationSeconds.

Hide child attributes

cuts.durationMs

integer

required

Length of the cut, in milliseconds

Required range: 0 < x <= 9007199254740991

Example:

750

cuts.startTimeMs

integer

required

Start of the cut, in ms of the raw recording

Required range: 0 <= x <= 9007199254740991

Example:

1500

microphoneVolume

number | null

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. Null is a no-op when the clip has no microphone audio. Non-null values return 400 when the clip has no microphone audio to control, i.e. whenever a read reports the field as absent.

Required range: 0 <= x <= 2

Example:

0.4

mirrorCamera

boolean

Mirror (flip horizontally) this clip's camera, like the editor's Mirror camera. Applies to this clip only. Returns 400 when the clip has no camera.

Example:

true

name

string

New clip name

Required string length: 1 - 255

Example:

"Updated intro"

order

integer

New position of the clip within the video

Required range: 0 <= x <= 9007199254740991

Example:

2

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.

Example:

false

systemAudioVolume

number | null

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. Null is a no-op when the clip has no system audio. Non-null values return 400 when the clip has no such audio to control, i.e. whenever a read reports the field as absent.

Required range: 0 <= x <= 2

Example:

1.5

transition

enum<string>

How this clip enters from the previous one. default drops the override and follows the video's defaultClipTransition.

Available options:

default,

smooth,

hard_cut

Example:

"default"

Response

Response shape for a single clip

clip

object

required

A section of a video

Hide child attributes

clip.background

object

required

Hide child attributes

clip.background.type

enum<string>

required

Available options:

solid,

gradient,

image,

video,

shaderGradient,

ambient

Example:

"solid"

clip.background.color

string | null

Hex color string. Required when type = 'solid'.

Example:

"#000000ff"

clip.background.gradientAngle

integer | null

Linear gradient angle in degrees. Required when type = 'gradient'.

Required range: -9007199254740991 <= x <= 9007199254740991

Example:

45

clip.background.gradientColor1

string | null

Hex color string. Required when type = 'gradient'.

Example:

"#ff0080ff"

clip.background.gradientColor2

string | null

Hex color string. Required when type = 'gradient'.

Example:

"#7928caff"

clip.background.imageUrl

string<uri> | null

Hosted image URL. Present in responses and accepted as input only when copied exactly from GET /v1/backgrounds; otherwise pass sourceId.

clip.background.shaderGradientPreset

string | null

Animated gradient preset from GET /v1/backgrounds. Required when type = 'shaderGradient'.

Example:

"Halo"

clip.background.sourceId

string | null

Example:

"su_abc123"

clip.background.videoDurationSeconds

number | null

Video background duration in seconds. Read-only: derived from the uploaded source or catalog entry on input.

Required range: x >= 0

Example:

12.4

clip.background.videoUrl

string<uri> | null

Hosted video URL. Present in responses and accepted as input only when copied exactly from GET /v1/backgrounds; otherwise pass sourceId.

clip.borderStyle

enum<string>

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.

Available options:

none,

subtle-shadow,

deep-shadow,

transparent,

solid-shadow-left,

solid-shadow-right,

snake,

glass,

custom

Example:

"subtle-shadow"

clip.corners

enum<string>

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.

Available options:

none,

regular,

squircle

Example:

"regular"

clip.createdAt

string<date-time>

required

ISO 8601 datetime

Example:

"2026-01-15T10:30:00.000Z"

clip.cuts

object[]

required

Time ranges cut from the clip's playback

Hide child attributes

clip.cuts.durationMs

integer

required

Length of the cut, in milliseconds

Required range: 0 < x <= 9007199254740991

Example:

750

clip.cuts.startTimeMs

integer

required

Start of the cut, in ms of the raw recording

Required range: 0 <= x <= 9007199254740991

Example:

1500

clip.durationSeconds

number

required

Effective playback duration of the clip after cuts, in seconds

Required range: x >= 0

Example:

12.5

clip.id

string

required

Unique clip identifier

Example:

"cl_xyz789ghi012"

clip.layoutSceneType

enum<string>

required

Determines which layouts can be applied to this clip via add_layout. See BasicSubjectLayoutName, CameraSubjectLayoutName, CombiLayoutName.

Available options:

basicSubject,

cameraSubject,

combi

Example:

"combi"

clip.maxDurationSeconds

number

required

Total length of the underlying source, in seconds

Required range: x >= 0

Example:

14.2

clip.name

string

required

Clip display name

Example:

"Intro"

clip.order

integer

required

Position of the clip within the video

Required range: 0 <= x <= 9007199254740991

Example:

0

clip.studioSound

boolean

required

Effective Studio Sound (AI audio enhancement) state for this clip: the video-level switch minus this clip's opt-out.

Example:

false

clip.transition

enum<string>

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.

Available options:

default,

smooth,

hard_cut

Example:

"default"

clip.updatedAt

string<date-time>

required

ISO 8601 datetime

Example:

"2026-01-15T14:45:00.000Z"

clip.videoId

string

required

Video identifier

Example:

"vid_abc123def456"

clip.animatedCursor

boolean

Whether the clip draws an animated cursor from captured mouse data. Absent when the clip has no screen recording.

Example:

true

clip.cameraCrop

object | null

The camera's crop; null when uncropped. Absent without a camera.

Hide child attributes

clip.cameraCrop.bottom

number

required

Pixels of the camera recording removed from its bottom edge

Required range: x >= 0

clip.cameraCrop.left

number

required

Pixels of the camera recording removed from its left edge

Required range: x >= 0

clip.cameraCrop.right

number

required

Pixels of the camera recording removed from its right edge

Required range: x >= 0

clip.cameraCrop.top

number

required

Pixels of the camera recording removed from its top edge

Required range: x >= 0

clip.cameraFocusPoint

object

The camera's focus point (50/50 when never set). Absent without a camera.

Hide child attributes

clip.cameraFocusPoint.xPct

number

required

Horizontal position, 0-100

Required range: 0 <= x <= 100

clip.cameraFocusPoint.yPct

number

required

Vertical position, 0-100

Required range: 0 <= x <= 100

Example:

{ "xPct": 50, "yPct": 35 }

clip.microphoneVolume

number | null

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).

Required range: 0 <= x <= 2

Example:

0.4

clip.mirrorCamera

boolean

Whether the clip's camera is mirrored (flipped horizontally). Absent when the clip has no camera.

Example:

false

clip.systemAudioVolume

number | null

This clip's system audio (screen or uploaded footage) volume override, with the same three states as microphoneVolume.

Required range: 0 <= x <= 2

Example:

null

Getting Started

Guides

MCP Tools

API Reference

Webhooks

Update a clip

Authorizations

Path Parameters

Body

Response