--- title: "Update a zoom" method: PATCH path: "/v1/videos/{id}/clips/{clipId}/zooms/{zoomId}" tags: ["Clips"] --- # Update a zoom `PATCH /v1/videos/{id}/clips/{clipId}/zooms/{zoomId}` ## Request - Base URL: `https://api.tella.com` - URL: `https://api.tella.com/v1/videos/{id}/clips/{clipId}/zooms/{zoomId}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Update a zoom's type, timing, focus point, or scale. Only the fields you send are changed. ## Path parameters - `id` string, required: Video ID - `clipId` string, required: Clip ID - `zoomId` string, required: Zoom ID ## Request body - UpdateClipZoomRequest: Update an existing zoom - `durationMs` integer - `focusPoint` ZoomFocusPoint: 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. - `introTransition` 'smooth' | 'hard_cut': How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly. - `outroTransition` 'smooth' | 'hard_cut': How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly. - `scale` number: Magnification factor (1 = no zoom, 3.5 = max). - `startTimeMs` integer: Start time in ms on the clip's playback timeline (cuts applied) - `type` 'manualZoom' | 'trackingZoom': `manualZoom` zooms into a fixed `focusPoint` on the screen. `trackingZoom` automatically follows the cursor in the screen recording. ## Response `200` OK - ClipZoomResponse: A zoom on a clip - `zoom` ClipZoom, required: A zoom effect applied to the footage in the clip's Screen slot — the screen recording, or b-roll media a layout puts there (the camera is unaffected). Use `manualZoom` with a `focusPoint`, or `trackingZoom` to follow the cursor automatically. Times are in ms on the clip's playback timeline (cuts applied). Internally the zoom stays anchored to the footage, so it doesn't drift when cuts change later. - `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-10-09** `25910750ad41`: 4 info - added the new optional request property `introTransition` - added the new optional request property `outroTransition` - added the required property `zoom/introTransition` to the response with the `200` status - added the required property `zoom/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 - **2026-09-09** `6b1132ef42fb`: 14 warning, 2 info - added the new `conflict` enum value to the `error` response property for the response status `400` - added the new `conflict` enum value to the `error` response property for the response status `401` - added the new `conflict` enum value to the `error` response property for the response status `403` - added the new `conflict` enum value to the `error` response property for the response status `404` - …12 more [Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/zooms/:zoomId/patch.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)