---
title: "Auto-generate zooms from mouse activity"
method: POST
path: "/v1/videos/{id}/clips/{clipId}/zooms/auto"
tags: ["Clips"]
---

# Auto-generate zooms from mouse activity

`POST /v1/videos/{id}/clips/{clipId}/zooms/auto`

## Request

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

Generates tracking zooms from the mouse clicks in the clip's screen recording — the API twin of 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.

## Path parameters

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

## Request body

- GenerateAutoZoomsRequest: 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` 'gentle' | 'subtle' | 'moderate' | 'focused' | 'intense' | 'slow' | 'medium' | 'fast': The editor's zoom preset: `gentle` (1.5x, the calmest, easing in softly), `subtle` (1.5x, slow and smooth), `moderate` (default, 2x), `focused` (2x, settles fast) or `intense` (2.5x, snappy). It also sets the clip's zoom animation style. `slow`, `medium` and `fast` mean subtle, moderate and intense.
  - `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.
  - `scale` number: Override the magnification factor (1 = no zoom, 3.5 = max). Defaults to the preset's scale (1.5 for gentle and subtle, 2 for moderate and focused, 2.5 for intense).

## Response `200`

OK

- GenerateAutoZoomsResponse: Zooms generated from the clip's mouse activity
  - `zooms` ClipZoom[], 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.
    - `durationMs` number, required: Duration in ms of playback. 0 when the zoom's footage is entirely cut out.
    - `focusPoint` ZoomFocusPointOutput: Point on the zoomed footage to zoom into, expressed as percentages of its dimensions. Required for `manualZoom`; ignored for `trackingZoom`.
      - `xPct` number, required: Horizontal position on the screen frame (0-100). 0 = left edge.
      - `yPct` number, required: Vertical position on the screen frame (0-100). 0 = top edge.
    - `id` string, required: Zoom ID
    - `introTransition` 'smooth' | 'hard_cut', required: How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly.
    - `outroTransition` 'smooth' | 'hard_cut', required: How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly.
    - `scale` number, nullable: Magnification factor (1 = no zoom, 3.5 = max).
    - `startTimeMs` number, required: Start time in ms on the clip's playback timeline (cuts applied)
    - `type` 'manualZoom' | 'trackingZoom', required: `manualZoom` zooms into a fixed `focusPoint` on the screen. `trackingZoom` automatically follows the cursor in the screen recording.

## 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

> 72 revisions in range; 1 not diffed.

- **2026-11-07** `0cc3fcd307ad`: 1 info
  - added the new `gentle` enum value to the request property `intensity`
- **2026-10-22** `063dd2193962`: 4 info
  - added the new `focused` enum value to the request property `intensity`
  - added the new `intense` enum value to the request property `intensity`
  - added the new `moderate` enum value to the request property `intensity`
  - added the new `subtle` enum value to the request property `intensity`
- **2026-10-09** `25910750ad41`: 2 info
  - added the required property `zooms/items/introTransition` to the response with the `200` status
  - added the required property `zooms/items/outroTransition` to the response with the `200` status
- **2026-09-28** `ac47c99c144f`: 9 warning
  - added the new `edit_conflict` enum value to the `error` response property for the response status `400`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `401`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `403`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `404`
  - …5 more
- …earlier changes not shown

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