Skip to main content
POST
/
v1
/
videos
/
{id}
/
clips
/
{clipId}
/
zooms
/
auto
Auto-generate zooms from mouse activity
curl --request POST \
  --url https://api.tella.com/v1/videos/{id}/clips/{clipId}/zooms/auto \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "intensity": "medium",
  "replaceExisting": true,
  "scale": 1.5
}
'
import requests

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

payload = {
"intensity": "medium",
"replaceExisting": True,
"scale": 1.5
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

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

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({intensity: 'medium', replaceExisting: true, scale: 1.5})
};

fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/zooms/auto', 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}/zooms/auto",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'intensity' => 'medium',
'replaceExisting' => true,
'scale' => 1.5
]),
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}/zooms/auto"

payload := strings.NewReader("{\n \"intensity\": \"medium\",\n \"replaceExisting\": true,\n \"scale\": 1.5\n}")

req, _ := http.NewRequest("POST", 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.post("https://api.tella.com/v1/videos/{id}/clips/{clipId}/zooms/auto")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"intensity\": \"medium\",\n \"replaceExisting\": true,\n \"scale\": 1.5\n}")
.asString();
require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"intensity\": \"medium\",\n \"replaceExisting\": true,\n \"scale\": 1.5\n}"

response = http.request(request)
puts response.read_body
{
  "zooms": [
    {
      "durationMs": 2000,
      "id": "ef_abc123",
      "startTimeMs": 1000,
      "type": "manualZoom",
      "focusPoint": {
        "xPct": 50,
        "yPct": 50
      },
      "scale": 2
    }
  ]
}
{
"error": {
"code": "bad_request",
"doc_url": "https://tella.tv/docs/api-reference/errors#bad-request",
"message": "The request was malformed or contained invalid parameters."
}
}
{
"error": {
"code": "unauthorized",
"doc_url": "https://tella.tv/docs/api-reference/errors#unauthorized",
"message": "Authentication is required. Provide a valid API key."
}
}
{
"error": {
"code": "forbidden",
"doc_url": "https://tella.tv/docs/api-reference/errors#forbidden",
"message": "You don't have permission to access this resource."
}
}
{
"error": {
"code": "not_found",
"doc_url": "https://tella.tv/docs/api-reference/errors#not-found",
"message": "The requested resource was not found."
}
}
{
"error": {
"code": "unprocessable_entity",
"doc_url": "https://tella.tv/docs/api-reference/errors#unprocessable-entity",
"message": "The request was well-formed but contained semantic errors."
}
}
{
"error": {
"code": "rate_limit_exceeded",
"doc_url": "https://tella.tv/docs/api-reference/errors#rate-limit-exceeded",
"message": "You have exceeded the rate limit. Please slow down."
}
}
{
"error": {
"code": "internal_server_error",
"doc_url": "https://tella.tv/docs/api-reference/errors#internal-server-error",
"message": "An unexpected error occurred on the server."
}
}

Authorizations

Authorization
string
header
required

API key obtained from your Tella account settings

Path Parameters

id
string
required

Video identifier

Example:

"vid_abc123def456"

clipId
string
required

Clip identifier

Example:

"cl_xyz789ghi012"

Body

application/json

Automatically generate tracking zooms from the mouse clicks in the clip's screen recording — the API twin of the editor's "Generate zooms". Warning: by default this replaces the clip's existing tracking zooms (see replaceExisting).

intensity
enum<string>

How aggressively to zoom. slow opens fewer, longer windows; fast opens shorter, tighter ones at a higher scale. Defaults to medium.

Available options:
slow,
medium,
fast
Example:

"medium"

replaceExisting
boolean

Defaults to true: the clip's existing tracking zooms are REMOVED before the generated ones are added, so repeated calls regenerate instead of stacking. Pass false to keep existing tracking zooms. Manual zooms are never touched.

Example:

true

scale
number

Override the magnification factor (1 = no zoom, 3.5 = max). Defaults to the intensity preset's scale (1.5 for slow/medium, 2 for fast).

Required range: 1 <= x <= 3.5
Example:

1.5

Response

OK

Zooms generated from the clip's mouse activity

zooms
object[]
required

The generated tracking zooms, in ms on the clip's playback timeline (cuts applied). Empty when the screen recording has no usable mouse clicks.