Editing the video

A finished video or the draft of a project without the AI director can be edited just like in the app's editor: cut words and pauses, split, trim, reorder and duplicate fragments, add a freeze frame, fix captions, add a hook, plaques, titles, emoji, zooms and markers, change speed (and the speed curve), sound, transitions, effects and colour, framing, mask, chroma key and keyframes, set music and voice, put your own photos and videos over the video — full frame or in a window, change the cover and the frame format. Edits are free and show up in the editor right away; the video file is updated by export. Only Slicer's AI features are paid: captions from speech, the AI assistant and caption translation, all at cost. Your agent can also edit the whole video itself, for free: it writes the plan, and Slicer applies the rules of its AI director to it — Your own director.

How edits work#

1. Get the video as text

   GET /v1/projects/{id}/transcript returns the video as text: fragments in order, words with id inside them, marks for cut and highlighted words, and elements — placed on words or by video time.

   {
     "rev": 7,
     "durationSec": 31.4,
     "text": "…",
     "blocks": [
       {
         "id": "b1",
         "position": 0,
         "sourceIndex": 0,
         "kind": "words",
         "words": [
           { "id": 12, "text": "Today", "cut": false, "accent": false },
           { "id": 13, "text": "I'll", "cut": false, "accent": false },
           { "id": 14, "text": "um", "cut": true, "accent": false },
           { "id": 15, "text": "show", "cut": false, "accent": true }
         ]
       },
       { "id": "b2", "position": 1, "sourceIndex": 2, "kind": "range", "words": [] }
     ],
     "elements": {
       "hook": "A reel in 3 minutes",
       "plaques": [],
       "cards": [],
       "emoji": [{ "id": "e1", "emoji": "🚀", "wordId": 15, "start": 1.2, "end": 2.4 }],
       "zooms": [{ "id": "z1", "fromWordId": 12, "toWordId": 15, "start": 0, "end": 2.4 }],
       "titles": [
         {
           "id": "t1", "text": "Step 1", "font": "punch", "size": 96, "color": "#FFFFFF", "background": "pill",
           "align": "center", "x": 540, "y": 420, "fromWordId": null, "toWordId": null,
           "start": 8, "end": 11, "anchor": { "blockId": "b2", "at": 3.5, "duration": 3 }
         }
       ],
       "markers": [{ "id": "m1", "time": 12.5, "label": "Music here", "color": "yellow" }]
     }
   }

   • kind: "words" is a speech fragment with words; kind: "range" is a fragment by source time: b-roll, a photo or a clip without recognized speech. It may have no words.
   • start and end of an element are where it sits in the video, in seconds. No start — the element isn't visible right now (its words are cut).
   • An element placed by time rather than on words comes with fromWordId: null and an anchor — the fragment, the second of its source and the duration (Elements by time).
   • markers are the author's notes on the timeline; they don't appear in the video.

   The text field is the same video as a single string in a form convenient for a language model: you can pass it to your own AI agent so it can suggest edits. Fragments without speech are shown in it with their time in the video.

2. Send operations

   POST /v1/projects/{id}/edits with the rev from step 1 and a list of operations (up to 80 at a time):

   {
     "rev": 7,
     "operations": [
       { "op": "cut_fillers" },
       { "op": "set_hook", "text": "A reel in 3 minutes" },
       { "op": "set_accent", "wordId": 18 },
       { "op": "set_emoji", "wordId": 18, "emoji": "🔥" },
       { "op": "add_plaque", "fromWordId": 20, "toWordId": 26, "kind": "list", "text": "Three steps", "caption": "Upload\nPick a style\nExport" },
       { "op": "add_title", "start": 8, "duration": 3, "text": "Step 1", "titleBackground": "pill", "titleIn": "pop" },
       { "op": "tune_block", "id": "b3", "transition": { "kind": "dissolve", "duration": 0.4 }, "animIn": { "kind": "zoomIn", "duration": 0.5 } }
     ]
   }

   { "ok": true, "data": { "rev": 8, "applied": 7, "skipped": [], "durationSec": 29.8 } }

3. Export when you're done

   Edits are saved immediately. To get an updated file, run an export — it's free.

Operations#

Slicer has a single operation catalog: the same operations are used by manual edits in the editor, the AI assistant, the director in the Chat, the API and the edit_project MCP tool. So the result matches what you'd get in the editor.

Words are addressed by their id from the video text, fragments and elements by their own id. A word range is fromWordId…toWordId, inclusive; fragment positions start at 0.

Speech and fragments#

Fragment and video settings#

Frame, mask, speed and sound over time#

Since API 1.5.0.

[
  { "op": "set_speed_curve", "id": "b4", "preset": "bullet" },
  { "op": "set_smooth", "id": "b4", "on": true },
  { "op": "set_keyframe", "id": "b5", "t": 0, "rotate": 0 },
  { "op": "set_keyframe", "id": "b5", "t": 2.5, "rotate": 12, "scale": 1.2 }
]

Captions#

Elements#

Elements are placed on words (fromWordId, toWordId or wordId) or — where there is no speech — by video time (start, duration).

Music and voice#

Since API 1.7.0. A track or a voice recording is a project source (sourceIndex) or a file from the project media (uploadId — your own files added to the project in the editor). Voice recording ids are in the edit document, the voices list.

[
  { "op": "set_music", "sourceIndex": 3, "volume": 0.25, "ducking": true, "fadeOut": 1.5 },
  { "op": "fit_music", "on": true },
  { "op": "fit_to_beats", "every": 2 }
]

Your photos and videos over the video#

Since API 1.7.0. An insert covers the picture with a photo or video while the speech goes on — for example, to show what the author is talking about. It is placed on words or by time, like elements; insert ids are in the edit document, the inserts list.

{ "op": "add_insert", "sourceIndex": 2, "fromWordId": 40, "toWordId": 52, "mode": "pip" }

Picture in picture#

Since API 1.6.0. An insert — your own photo or video over the video (its id is in the edit document, the inserts list) — can cover the whole frame or sit in a window.

{ "op": "set_pip", "id": "i4k2m9q", "x": 800, "y": 1500, "scale": 0.4, "shape": "circle", "borderColor": "#ffffff", "borderWidth": 0.03 }

Window keyframes are set in the editor; in the edit document they are inserts[].pip.keyframes.

Values#

• speed — 0.25 to 4; volume — 0 to 1; fadeIn, fadeOut — 0 to 3 seconds;
• effect — shake, pulse, flash, cinema, vignette, grain, blur, glitch, vhs;
• transition — { "kind", "duration" }, duration — 0.2 to 1.2 seconds; kind — fade, flash, zoom, dissolve, blur, slides slide, slideRight, slideUp, slideDown, wipes wipe, wipeRight, wipeUp, wipeDown, circle circleOpen and circleClose, zoomIn, pixelize, radial, scatter;
• filter — { "id", "strength" }, filter — bw, warm, cool, vintage, sepia, vivid, pastel, noir, cinema, strength — 0 to 1;
• adjust — Adjust: exposure, brightness, contrast, saturation, temperature, tint, each from −1 to 1 (0.15 is a noticeable step); replaces all of the fragment's sliders at once;
• lut — { "preset", "strength" } or { "uploadId", "strength" }: a built-in LUT — teal-orange, film, matte, bleach, golden, moody, nordic, cross, mono-film, vibrant; uploadId — your own .cube from My LUTs (its id is in the edit document on a fragment that uses it); strength — 0 to 1;
• animIn, animOut — { "kind", "duration" }, kind — fade, zoomIn, zoomOut, slideLeft, slideRight, slideUp, slideDown, duration — 0.2 to 2 seconds.

A title's look uses fields with the title prefix; in update_title, null resets a field:

The full operation schema:

Elements by time#

A video without speech — b-roll, photos, a draft without recognized speech — has no words, so plaques, titles, emoji, zooms, cards and markers are placed by time: start is a second of the video, duration is the length in seconds of the video (0.3–60).

{ "op": "add_title", "start": 4, "duration": 2.5, "text": "Morning at the coffee shop", "titleIn": "typewriter" }

{ "op": "add_zoom", "start": 9, "duration": 2, "scale": 1.2, "motion": "pull" }

An element holds on to the fragment it sits over, like a connected clip: move the fragment — the element moves with it; delete the fragment — the element goes too. Over speech, prefer placing elements on words: that placement survives text edits. If an operation has both words and time, the words win.

Skipped operations#

Operations are applied in order. If an operation changes nothing — the word isn't found, the fragment doesn't exist, the emoji isn't in the set — it's skipped and the rest are applied. Skipped operations are listed in skipped:

{ "rev": 9, "applied": 2, "skipped": [{ "index": 1, "op": "remove_plaque", "reason": "element_not_found" }], "durationSec": 29.8 }

Revisions#

A video has a revision number rev; every saved edit increases it. An edit with an outdated revision is rejected with 409 stale_document — the video was changed in the editor or by another request. Re-read the video text and repeat the edit with the new rev. This way edits from the API and the app never overwrite each other.

Captions from speech#

In a project without the AI director the speech isn't recognised, so there are no captions, and the fragments in the video text are by time. POST /v1/projects/{id}/transcribe recognises the speech in the sources — like Captions from speech in the editor (Captions from speech). It also recognises sources added to a project after the montage.

curl https://api.slicer.media/v1/projects/318/transcribe \
  -H "Authorization: Bearer $SLICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language":"auto"}'

Recognition is priced at cost per minute of sound of the chosen sources: without confirmCost you get a Quote with estimate (the expected price) and cost (the maximum), atCost: true — as with the AI assistant. Repeat the request with "confirmCost" equal to cost: the tokens are reserved, and the actual cost is charged, never more than cost. Requires the montage:run scope.

Recognition runs in the background. The response to the start is a job { id, status, sources, createdAt }; follow it with GET /v1/projects/{id}/transcribe, the project's job list:

When the job is ready, re-read GET /v1/projects/{id}/transcript: the fragments now have words with ids, you can place elements on them and edit captions (set_text, set_accent, set_phrase_text). The edit document itself doesn't change. POST /v1/estimate with kind: "transcribe" and projectId names the price in advance.

AI assistant#

A command in plain words — the assistant picks the operations from the same catalog itself:

curl https://api.slicer.media/v1/projects/318/assistant \
  -H "Authorization: Bearer $SLICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"Make the video more dynamic and add emoji on the key words","rev":9}'

The assistant is priced at cost: a command costs exactly what its AI calls cost, with no markup. Without confirmCost you get the price:

{ "ok": true, "data": { "status": "quote", "cost": 2, "free": false, "estimate": 0.4, "atCost": true, "available": 240, "enough": true, "spendLimitLeft": 176 } }

• atCost: true — the operation is priced at cost;
• estimate — the expected price in tokens, fractional;
• cost — the maximum price: repeat the request with "confirmCost" equal to it. The actual cost is charged, never more than cost.

With confirmCost the response is { rev, summary, applied, charged, costTokens, durationSec }: summary describes what was done, costTokens is the actual cost of the command (fractional), charged is how many whole tokens were taken from the balance now. The fractional remainder accumulates with the project and is charged once it adds up to a whole token. Tokens are charged only if the assistant changed something. Requires the montage:run scope.

Caption translation#

POST /v1/projects/{id}/translate with language — en, es, pt, de, fr, it, pl, tr, id, uk, ru — and rev. The translation is laid out word by word, so accents and emoji stay in place. Translation is priced at cost too: the price (Quote with estimate and cost) and confirmation work as for the assistant. The response is { rev, phrases, charged, costTokens }; you're charged only if the translation succeeded.

Auto color#

POST /v1/projects/{id}/auto-color balances color without AI and for free — from 10 frames of the fragment, like the Auto and Match all to this buttons in the editor. The body has rev, blockId and mode:

• auto — correct fragment blockId: exposure, contrast, saturation and white balance;
• match — make the other fragments look like blockId: they get its filter and LUT, and each gets its own Adjust values.

{ "rev": 7, "blockId": "b2", "mode": "match" }

The result is saved right away. The response has the new revision, Adjust values by fragment id (adjust), how many fragments changed (applied) and the video's duration.

Your own director#

Your AI agent can edit the video itself — on its side, for free in Slicer: it looks at the frames and writes the plan, and Slicer applies the rules of its AI director to the plan on the server and answers with fixes and issues. The rules themselves are not passed to the agent. How it works step by step — Your own director in the MCP section: the get_director_brief, get_frames and submit_director_plan tools are built on these routes.

All three are free. If the video has speech, recognise it first — Captions from speech (at cost): without words the director has nothing to cut.

Brief#

The body is optional: director settings — mode (auto, talking, story, product, aesthetic), pace (calm, balanced, dynamic), effects (off, light, bold), targetDurationSec (10–180, null — the director decides, up to 90 seconds), hook, plaques, emoji, cameraMotion. Fields you pass are saved to the project: Slicer applies the rules to the plan by them.

curl https://api.slicer.media/v1/projects/318/director/brief \
  -H "Authorization: Bearer $SLICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pace":"dynamic","targetDurationSec":30}'

Frames#

times — seconds of the source, comma-separated (up to 16), or evenly: from, to, count (8 frames over the whole source by default). Seconds outside the source are clamped to its edge. A photo returns one image; audio has no frames (400 no_picture), a missing source — 404 source_not_found.

curl "https://api.slicer.media/v1/projects/318/sources/0/frames?times=2.5,7,12.4" \
  -H "Authorization: Bearer $SLICER_TOKEN"

{ "ok": true, "data": { "sourceIndex": 0, "durationSec": 48.2, "frames": [{ "time": 2.5, "mimeType": "image/jpeg", "data": "/9j/4AAQ…" }] } }

Plan#

The body has rev (from the brief or from the previous answer), plan in planSchema and, optionally, scenes — up to 400 observations in scenesSchema: sourceIndex, start and end in seconds of the source, kind (talking_head, demo, people, screen, broll, unusable), interest from 1 to 5 and description. What the kinds mean and how Slicer places footage by them — Observations from the frames.

{
  "rev": 3,
  "plan": {
    "concept": "Three steps from milk to pattern",
    "segments": [
      { "kind": "speech", "role": "hook", "fromWordId": 41, "toWordId": 47, "why": "A strong opening" },
      { "kind": "footage", "role": "body", "sourceIndex": 0, "fromSec": 14.5, "toSec": 19, "why": "Showing the pattern" }
    ],
    "hook": "Latte art in a minute"
  },
  "scenes": [
    { "sourceIndex": 0, "start": 0, "end": 14.5, "kind": "talking_head", "interest": 3, "description": "The barista talks at the counter" },
    { "sourceIndex": 0, "start": 14.5, "end": 21, "kind": "demo", "interest": 5, "description": "Draws a heart on a latte" }
  ]
}

On the server the rules of the Slicer director are applied to the plan: speech by words, footage by the observations, restrained editing, length. The plan becomes the video right away — a new revision, even if it has issues. Media cards from a description are not accepted — their picture is paid; the update_card operation sets your own photo. Fragments are framed in the centre; fix the framing with the set_framing operation.

Plan issues#

An issue is { code, segment, message }: a code, the plan fragment number from zero (only if the issue is about a fragment) and what to fix — in English, for the model to read. Fix the plan and send the whole plan again with the new rev; when issues is empty, the plan is fine.

Style#

PATCH /v1/projects/{id}/style changes the template, font, accent color, caption look, sound effects and intro zoom — for free. The change is partial: only the fields you pass change, everything else — including the other fields of subtitles and params — stays as it was.

{ "templateId": "clean", "fontId": "editorial", "colorId": "mint", "subtitles": { "design": "karaoke", "size": "large" } }

The new style shows in the editor right away and in the file after export. To have the AI rebuild the video with different montage settings, use a rebuild.

Caption look#

The subtitles fields are the same as in the editor's Caption style sheet (Captions). Word highlight, entrance, words on screen, letter case and colour by speaker — since API 1.8.0.

highlight, animation, words and letterCase also take auto, the default: the way the design intends (for letterCase — the font). The templates are bold, clean and pop.

{ "subtitles": { "highlight": "pop" } }

How a subtitles change behaves:

• only the fields you pass change, the others stay as they were. Before API 1.8.0 a partial subtitles change reset the other fields to their defaults;
• a new design without highlight, animation and words resets them to auto — like picking a design in the editor: the design looks the way it is meant to right away. Size, position, letter case and colour by speaker stay. To change the design and set the highlight at once, pass both fields:

{ "subtitles": { "design": "karaoke", "highlight": "pop" } }

Names and descriptions of the values in both languages are in the GET /v1/styles catalog: designs — subtitleDesigns, positions — subtitlePositions, word highlight, entrance, words on screen and letter case — subtitleOptions:

[
  {
    "id": "highlight",
    "title": { "ru": "Выделение слова", "en": "Word highlight" },
    "help": { "ru": "Как выделяется слово, которое сейчас звучит.", "en": "How the word being spoken is highlighted." },
    "values": [
      { "id": "auto", "title": { "ru": "Как в оформлении", "en": "As in the style" }, "description": { "ru": "Так, как задумано выбранным оформлением.", "en": "As the chosen style intends." } },
      { "id": "pop", "title": { "ru": "Увеличение", "en": "Pop" }, "description": { "ru": "Слово, которое звучит, увеличивается и подсвечивается, соседние слова плавно расступаются.", "en": "The spoken word grows and lights up, the others smoothly make room." } }
    ]
  }
]

The same fields are accepted by settings.subtitles when you create a project (Video settings) and by the set_style MCP tool.

The edit document (advanced)#

GET /v1/projects/{id}/document returns the whole edit document — the complete description of the video that the preview and the render are built from — with its revision. A PUT to the same path with { rev, document } replaces it entirely. The document goes through the same checks as edits from the editor; unknown fields are dropped.

Example: remove fillers and add a hook#

// node polish.mjs 318
const API = 'https://api.slicer.media/v1';
const headers = { Authorization: `Bearer ${process.env.SLICER_TOKEN}`, 'Content-Type': 'application/json' };
const id = process.argv[2];

async function call(method, path, body) {
  const response = await fetch(`${API}${path}`, { method, headers, body: body && JSON.stringify(body) });
  const json = await response.json();
  if (!json.ok) throw Object.assign(new Error(json.error.message), { code: json.error.code });
  return json.data;
}

for (let attempt = 0; attempt < 3; attempt += 1) {
  const { rev, blocks } = await call('GET', `/projects/${id}/transcript`);
  const words = blocks.flatMap((block) => block.words).filter((word) => !word.cut);
  try {
    const result = await call('POST', `/projects/${id}/edits`, {
      rev,
      operations: [
        { op: 'cut_fillers' },
        { op: 'set_hook', text: 'A reel in 3 minutes' },
        { op: 'set_accent', wordId: words[0].id },
      ],
    });
    console.log(`Applied: ${result.applied}, length: ${result.durationSec} s`);
    break;
  } catch (error) {
    if (error.code !== 'stale_document') throw error; // the video changed — re-read and retry
  }
}

# python polish.py 318
import os
import sys

import requests

API = "https://api.slicer.media/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SLICER_TOKEN']}"
project_id = sys.argv[1]


class ApiError(Exception):
    def __init__(self, error):
        super().__init__(error["message"])
        self.code = error["code"]


def call(method, path, json=None):
    body = session.request(method, API + path, json=json, timeout=60).json()
    if not body["ok"]:
        raise ApiError(body["error"])
    return body["data"]


for attempt in range(3):
    transcript = call("GET", f"/projects/{project_id}/transcript")
    words = [w for block in transcript["blocks"] for w in block["words"] if not w["cut"]]
    try:
        result = call("POST", f"/projects/{project_id}/edits", {
            "rev": transcript["rev"],
            "operations": [
                {"op": "cut_fillers"},
                {"op": "set_hook", "text": "A reel in 3 minutes"},
                {"op": "set_accent", "wordId": words[0]["id"]},
            ],
        })
        print(f"Applied: {result['applied']}, length: {result['durationSec']} s")
        break
    except ApiError as error:
        if error.code != "stale_document":  # the video changed — re-read and retry
            raise

What's next#