Batch edits

​

apply_video_edits

​

Supported operations

• Updates and removes take the target resource ID and the clipId; updates also take only the fields being changed (including transition and depth on media and text overlays). Media and text overlay adds accept depth too, so new overlays can go behind the presenter without a second call. Text overlay adds also accept transition, so a new title can fade in without a follow-up update.
• Blur and highlight adds and updates accept transition (smooth or hard_cut), as on the standalone tools. New blurs and highlights default to hard_cut.
• update_media_overlay and update_text_overlay accept zIndex to change stacking order, as on update_overlay and update_text_overlay. Each zIndex applies to the stack as earlier operations in the batch left it: adds join the front, removes leave the stack, and you can restack an overlay added earlier in the same batch by its operationId. A negative zIndex rejects the whole batch.
• Media and text overlay adds and updates accept animation for entrance and exit effects. See Animate overlays and Animate text overlays. Invalid animation values reject the whole batch before any edits apply.
• Text overlay adds and updates accept fontId for a font in your private or workspace library, instead of fontFamily. See Use a custom font; an unknown font rejects the whole batch before any edits are applied.
• Zoom operations use zoomType for the zoom variant, because type selects the batch operation itself.
• Cuts, transcript edits and clip settings are not batchable. For custom layout geometry or a layout’s crop, call add_layout or update_layout separately for each layout; apply_video_edits accepts named layout kinds only.

​

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.

​

Retrying a batch

• To resend safely after losing a response, include _meta.idempotencyKey and reuse the same key — see 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

{
  "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
    }
  ]
}

{
  "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"
    }
  ]
}