# Версии и совместимость

> Как Slicer версионирует API — версия в пути, только добавляющие изменения внутри v1, номер спецификации и правила для клиентов.

Источник: https://docs.slicer.media/api/versioning/

Мы хотим, чтобы код, написанный сегодня, работал и через год. Поэтому у API два уровня версий и строгие правила, что можно менять внутри одной версии.

## Версия в пути

Основная версия — в адресе: `https://api.slicer.media/v1`. Внутри `/v1` изменения **только добавляющие**:

-   новые эндпоинты;
-   новые необязательные поля в запросах и новые поля в ответах;
-   новые значения в конце перечислений (например, новый статус публикации или новый шрифт в каталоге);
-   новые события вебхуков и новые коды ошибок.

Удалить поле, переименовать его, поменять смысл или тип, сделать необязательное поле обязательным — это несовместимое изменение. Оно возможно только в `/v2`, и после её выхода `/v1` продолжает работать не меньше 12 месяцев.

## Номер спецификации

Спецификация API — [`GET /v1/openapi.json`](https://api.slicer.media/v1/openapi.json) (OpenAPI 3.1) — имеет свой номер в формате semver в поле `info.version`. Сейчас это `1.10.0`.

| Часть номера | Когда растёт |
| --- | --- |
| минорная (`1.1.0`) | добавили эндпоинт, поле, событие, значение перечисления |
| патч (`1.0.1`) | исправили описание или поведение, не меняя контракт |
| основная (`2.0.0`) | вместе с новым путём `/v2` |

MCP-сервер использует тот же номер — его инструменты построены на тех же контрактах. Каждое изменение API и MCP публикуется в [журнале изменений](https://docs.slicer.media/changelog/) с меткой «Изменение API»: что поменялось в спецификации и нужно ли что-то делать клиентам.

## История версий

Все версии ниже — внутри `/v1` и только добавляют возможности: клиент, написанный под `1.0.0`, работает без изменений.

| Версия | Дата | Что добавилось |
| --- | --- | --- |
| `1.10.0` | 28.10.2026 | Монтаж отдаёт одну версию, проверенную режиссёром: `versionChoice` после монтажа — `null`, событие `project.version_ready` не приходит. `POST /v1/projects/{id}/versions/{versionId}/choose` и MCP `choose_version` делают текущей и любую версию из истории с файлом (`hasFile`), например ролик до пересборки ([Версии ролика](https://docs.slicer.media/api/montage/#versions)) |
| `1.9.0` | 27.10.2026 | Переход «Звук раньше»: вид `jcut` в переходах операций `tune_block` и `set_all_transitions`, длительность — от 0,15 до 1 с ([Переходы](https://docs.slicer.media/guide/editor/transitions/#audio-lead)) |
| `1.8.0` | 19.10.2026 | Субтитры: оформления `pop`, `box`, `word` и шаблон `pop`; в `subtitles` стиля (`PATCH /v1/projects/{id}/style`, MCP `set_style`) и настроек монтажа — поля `highlight` (выделение слова, которое звучит), `animation` (появление фразы), `words` (слов на экране), `letterCase` (регистр) и `speakerColors`; `subtitleOptions` в каталоге `GET /v1/styles`. Частичная правка `subtitles` сохраняет остальные поля, новое `design` без `highlight`, `animation` и `words` возвращает их к `auto`. `position: "auto"` ставит каждую фразу туда, где в кадре больше свободного места ([Стиль](https://docs.slicer.media/api/editing/#style)) |
| `1.7.0` | 19.10.2026 | Правки — всё, что умеет таймлайн: операции нарезки `split_block`, `trim_block`, `duplicate_block`, `freeze_frame`, `set_hold`, `replace_source`; бесплатная обработка `set_process` и движение камеры `apply_keyframe_preset`; музыка `set_music`, `remove_music`, `fit_music`, `fit_to_beats`; голос на дорожке `add_voice`, `move_voice`, `trim_voice`, `set_voice_volume`, `remove_voice`; свои фото и видео поверх ролика `add_insert`, `update_insert`, `remove_insert`; `update_plaque`, `update_card`, `update_zoom`, `set_element_position`, `set_phrase_text`, `reset_phrase_text`; поле `background` в `tune_block`, звуки и маркеры в `move_element`. Причины пропуска `block_or_source_not_found`, `audio_not_found`, `no_music_or_beats`, `recording_not_found`, `media_or_place_not_found`, `word_not_found`. Субтитры из речи: `POST /v1/projects/{id}/transcribe` (по себестоимости, без `confirmCost` — `Quote`) и `GET /v1/projects/{id}/transcribe` — задачи распознавания, вид `transcribe` в `POST /v1/estimate`, инструменты MCP `transcribe_speech` и `get_transcribe_jobs`. В MCP `create_project` по умолчанию создаёт проект без ИИ-режиссёра (`mode: "manual"`). [Свой режиссёр](https://docs.slicer.media/api/editing/#own-director): `POST /v1/projects/{id}/director/brief`, `GET /v1/projects/{id}/sources/{index}/frames`, `POST /v1/projects/{id}/director/plan` — бесплатно, инструменты MCP `get_director_brief`, `get_frames`, `submit_director_plan` и промпт `direct_reel` |
| `1.6.0` | 18.10.2026 | Картинка в картинке: операция `set_pip` — вставка окном поверх ролика или снова во весь кадр (положение, размер, поворот, непрозрачность, форма, скругление, рамка, звук), поле `pip` у вставок в документе монтажа |
| `1.5.0` | 18.10.2026 | Кадр и движение: операции `set_framing` (в том числе `track` — кадр следит за лицом), `set_keyframe` и `remove_keyframe` (поворот, непрозрачность, сглаживание), `set_mask` (положение, поворот, инверсия, анимация), `set_chromakey` — хромакей, `set_speed_curve` — кривая скорости видеоряда, `set_smooth` — сверхзамедление, `set_volume_keys` — громкость по точкам. Причины пропуска `block_not_footage`, `keyframe_not_found`, `block_not_found_or_no_face_data` |
| `1.4.0` | 17.10.2026 | Цвет: `POST /v1/projects/{id}/auto-color` и инструмент MCP `auto_color`, `adjust` и `lut` в `tune_block` и `set_all_color`. Звуки автора: операции `add_sound`, `update_sound`, `remove_sound` |
| `1.3.0` | 17.10.2026 | Маркеры: операции `add_marker`, `update_marker`, `remove_marker` и `elements.markers` в тексте ролика. Нарастание и затухание звука фрагмента (`fadeIn`, `fadeOut` в `tune_block`). Операции `apply_look` — оформление одного фрагмента на другие, `slip_block` — сдвиг кадра у фрагмента видеоряда, `set_cover` — обложка с заголовком. 12 новых видов перехода |
| `1.2.0` | 17.10.2026 | Титры — свободные текстовые слои: операции `add_title`, `update_title`, `remove_title` и `elements.titles`. Операция `add_source` — поставить исходник проекта в ролик новым фрагментом |
| `1.1.0` | 17.10.2026 | Проект без ИИ-режиссёра: `mode: "manual"` и `format` в `POST /v1/projects`, поле `mode` и статус `draft` у проекта, фильтр `status=draft`. Элементы по времени ролика (`start`, `duration`) там, где нет речи, и привязка `anchor` в тексте ролика. Единый каталог операций: `cut_silences`, `move_element`, `set_all_color`, анимации в `tune_block`, масштаб и движение у `add_zoom`. ИИ-помощник и перевод — по себестоимости: `estimate` и `atCost` в `Quote`, `costTokens` в ответе |
| `1.0.0` | 16.10.2026 | Первая версия: загрузки, монтаж с подтверждением цены, три версии ролика, правки операциями, ИИ-помощник, перевод, стиль, экспорт и публикация, вебхуки |

Подробности каждой версии — в [журнале изменений](https://docs.slicer.media/changelog/).

## Как писать устойчивый клиент

-   **Игнорируйте незнакомые поля** в ответах и вебхуках — новые поля появятся без предупреждения.
-   **Будьте готовы к новым значениям перечислений.** Если пришёл неизвестный `status` или тип события, обработайте его как «прочее», а не падайте. Пример — статус `draft`, появившийся в `1.1.0`.
-   **Не полагайтесь на порядок полей** в JSON и на точный текст `message` — только на `code`.
-   **Отправляйте только нужные поля.** Неизвестные поля в теле запроса сервер отбрасывает; опечатка в имени поля не вызовет ошибку, но и не сработает — сверяйтесь со [справочником](https://docs.slicer.media/api/reference/).
-   **Документ монтажа** (`GET /v1/projects/{id}/document`) — внутренняя модель ролика, в v1 в ней тоже только добавляются поля. Для правок надёжнее [операции](https://docs.slicer.media/api/editing/): они не зависят от устройства документа.

## Генерация клиента

Спецификацию можно отдать генератору клиентов — например, `openapi-typescript` для TypeScript или `openapi-python-client` для Python:

Терминал:

```bash
npx openapi-typescript https://api.slicer.media/v1/openapi.json -o slicer-api.d.ts
```

Спецификация доступна без токена. Справочник этой документации строится из неё же, поэтому документация и сервер не расходятся.

## Что дальше

[СправочникВсе эндпоинты v1.](https://docs.slicer.media/api/reference/)[Журнал измененийЧто нового в API, MCP и приложении.](https://docs.slicer.media/changelog/)