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

# Batch edits

> Apply up to 200 timeline edits across a video's clips in one call with apply_video_edits.

## apply\_video\_edits

Use `apply_video_edits` whenever you need two or more timeline edits. It takes up to 200 mixed operations across any clips in one video, validates the whole request, and applies it as a single editor revision — substantially faster than repeated single-edit calls. For one edit, the standalone tool is still the convenient choice.

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

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

<ParamField path="operations" type="object[]" required>
  1–200 operations, run in array order. Each one carries `type`, a unique `operationId`, a `clipId`, and the same fields as the standalone tool it mirrors.
</ParamField>

### Supported operations

| Resource                 | `type` values                                                       | Standalone tools                                        |
| ------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------- |
| Sound effects            | `add_sound_effect`, `update_sound_effect`, `remove_sound_effect`    | [Sound effects](/docs/mcp-tools/sound-effects)               |
| Text overlays            | `add_text_overlay`, `update_text_overlay`, `remove_text_overlay`    | [Text overlays](/docs/mcp-tools/text-overlays)               |
| Zooms                    | `add_zoom`, `update_zoom`, `remove_zoom`                            | [Zooms](/docs/mcp-tools/zooms)                               |
| Blurs                    | `add_blur`, `update_blur`, `remove_blur`                            | [Blurs and highlights](/docs/mcp-tools/blurs-and-highlights) |
| Highlights               | `add_highlight`, `update_highlight`, `remove_highlight`             | [Blurs and highlights](/docs/mcp-tools/blurs-and-highlights) |
| Image and video overlays | `add_media_overlay`, `update_media_overlay`, `remove_media_overlay` | [Overlays](/docs/mcp-tools/overlays)                         |
| Layouts                  | `add_layout`, `update_layout`, `remove_layout`                      | [Layouts](/docs/mcp-tools/layouts)                           |

* Updates and removes take the target resource ID and the `clipId`; updates also take only the fields being changed (including `transition` on media and text overlays).
* Zoom operations use `zoomType` for the zoom variant, because `type` selects the batch operation itself.
* Cuts, transcript edits, clip settings, and `generate_auto_layouts` are not batchable.

### How a batch runs

* **Results match by `operationId`.** Adds return the created resource ID; updates and removes return the affected one.
* **Later operations can reference earlier adds.** Pass an add's `operationId` in place of the resource ID — for example, add a zoom and re-time it later in the same batch.
* **Validation is all-or-nothing.** Schema, resource existence, timeline bounds, and cross-references are checked upfront. One invalid operation rejects the whole call with `invalid_argument` naming that operation, before anything is applied.
* **Removed resources stay removed.** Removing a resource that doesn't exist (or was already removed) is an error, and later operations in the batch can no longer target it.

<Accordion title="Layout operations">
  Layout operations accept the same B-roll `media` field as [`add_layout`](/docs/mcp-tools/layouts#add_layout) and [`update_layout`](/docs/mcp-tools/layouts#update_layout).

  * A time-ranged `add_layout` can provide `media` and omit `layout` to use the default full-frame B-roll layout. It trims, splits, or removes overlapping layouts to make room, exactly like the standalone call.
  * `update_layout` can replace either media slot while keeping the other, and can reshape media-bearing layouts.
  * An add without a range sets the clip's base layout and returns the ID `base`. `update_layout` accepts `base` (or the `operationId` of a clip-spanning add), but the base layout accepts `layout` only.
</Accordion>

### Retrying a batch

<Warning>
  Without an idempotency key the call is **not** idempotent. Re-sending a batch after a success re-applies its adds as new resources, and its removes then fail validation because their targets are already gone — so the retried batch is rejected as a whole.
</Warning>

* To resend safely after losing a response, include `_meta.idempotencyKey` and reuse the same key — see [Retrying tool calls safely](/docs/mcp-server#retrying-tool-calls-safely).
* Otherwise, retry only when the previous call definitely did not apply, such as after a rate limit or a pre-execution `unavailable` error.
* A `revision` in the response is proof the batch landed.

### Examples

Two adds on one clip:

```json theme={null}
{
  "videoId": "vid_123",
  "operations": [
    {
      "type": "add_sound_effect",
      "operationId": "click-1",
      "clipId": "cl_123",
      "presetId": "mouse-click",
      "startTimeMs": 1200,
      "durationMs": 300
    },
    {
      "type": "add_text_overlay",
      "operationId": "title-1",
      "clipId": "cl_123",
      "text": "Welcome",
      "startTimeMs": 0,
      "durationMs": 5000
    }
  ]
}
```

A mixed batch — add a zoom, update an existing text overlay, and remove a sound effect in one revision:

```json theme={null}
{
  "videoId": "vid_123",
  "operations": [
    {
      "type": "add_zoom",
      "operationId": "zoom-1",
      "clipId": "cl_123",
      "zoomType": "trackingZoom",
      "startTimeMs": 2000,
      "durationMs": 3000,
      "scale": 2
    },
    {
      "type": "update_text_overlay",
      "operationId": "retitle-1",
      "clipId": "cl_123",
      "textOverlayId": "ly_456",
      "text": "Updated title"
    },
    {
      "type": "remove_sound_effect",
      "operationId": "drop-click",
      "clipId": "cl_123",
      "soundEffectId": "ly_789"
    }
  ]
}
```


## Related topics

- [Model Context Protocol (MCP)](/docs/mcp-server.md)
- [Batch export videos](/docs/help/export-videos/batch-export-videos.md)
- [How to batch upload multiple videos from your computer](/docs/help/faq/batch-upload.md)
- [Apply many video edits](/docs/api-reference/videos/apply-many-video-edits.md)
- [Rate limiting](/docs/rate-limiting.md)