> ## Documentation Index
> Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Zooms

> Zoom into a point on the screen, follow the cursor, or generate zooms from clicks.

Zoom into a specific point on the clip's screen layer for a time range (the camera is unaffected). Use `manualZoom` for a fixed focus point or `trackingZoom` to follow the cursor in the screen recording.

<Note>
  **All times are milliseconds on the clip's playback timeline** — the video as watched, with cuts applied. It is the same timeline as `get_transcript`, thumbnails, and previews, so nothing needs converting. A start at or past the end of the clip is rejected with a `400`.
</Note>

## list\_zooms

List zooms on a clip.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

## add\_zoom

Add a zoom to a clip.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="type" type="enum<string>" required>
  `manualZoom` or `trackingZoom`
</ParamField>

<ParamField path="startTimeMs" type="integer" required>
  Start time in ms
</ParamField>

<ParamField path="durationMs" type="integer" required>
  Duration in ms
</ParamField>

<ParamField path="focusPoint" type="object">
  Required for `manualZoom` (rejected if missing); ignored for `trackingZoom`. Percentages — `{xPct, yPct}` (0-100).

  <Expandable title="properties">
    <ParamField path="xPct" type="number" required>
      Horizontal position on the screen (0-100)
    </ParamField>

    <ParamField path="yPct" type="number" required>
      Vertical position on the screen (0-100)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="scale" type="number" required>
  Magnification factor (1 = no zoom, 3.5 = max). A zoom without a scale cannot be rendered.
</ParamField>

## update\_zoom

Update an existing zoom. Only provided fields change.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="zoomId" type="string" required>
  Zoom ID
</ParamField>

<ParamField path="type" type="enum<string>">
  `manualZoom` or `trackingZoom`
</ParamField>

<ParamField path="startTimeMs" type="integer">
  New start time in ms
</ParamField>

<ParamField path="durationMs" type="integer">
  New duration
</ParamField>

<ParamField path="focusPoint" type="object">
  New focus point

  <Expandable title="properties">
    <ParamField path="xPct" type="number" required>
      Horizontal position on the screen (0-100)
    </ParamField>

    <ParamField path="yPct" type="number" required>
      Vertical position on the screen (0-100)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="scale" type="number">
  New magnification
</ParamField>

## remove\_zoom

Remove a zoom from a clip.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="zoomId" type="string" required>
  Zoom ID
</ParamField>

## generate\_auto\_zooms

Automatically generate tracking zooms from the mouse clicks in the clip's screen recording — the same as the editor's "Generate zooms". Every click opens a zoom window; nearby windows are merged. Requires the clip to contain a screen recording; returns an empty list when it has no usable mouse clicks.

<Warning>
  By default this removes the clip's existing tracking zooms first, so repeated calls regenerate instead of stacking. Pass `replaceExisting: false` to keep them. Manual zooms are never touched.
</Warning>

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="intensity" type="enum<string>">
  How aggressively to zoom — `slow`, `medium` (default), or `fast`. `slow` opens fewer, longer windows; `fast` opens shorter, tighter ones at a higher scale.
</ParamField>

<ParamField path="scale" type="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).
</ParamField>

<ParamField path="replaceExisting" type="boolean">
  Defaults to `true` — existing tracking zooms are removed first. Pass `false` to keep them.
</ParamField>


## Related topics

- [Update a zoom](/docs/api-reference/clips/update-a-zoom.md)
- [Remove a zoom](/docs/api-reference/clips/remove-a-zoom.md)
- [Add a zoom to a clip](/docs/api-reference/clips/add-a-zoom-to-a-clip.md)
- [List zooms on a clip](/docs/api-reference/clips/list-zooms-on-a-clip.md)
- [Add zooms and screen effects](/docs/help/editing/add-a-zoom.md)