Версии и совместимость
Как Slicer версионирует API — версия в пути, только добавляющие изменения внутри v1, номер спецификации и правила для клиентов.
На этой странице
Мы хотим, чтобы код, написанный сегодня, работал и через год. Поэтому у API два уровня версий и строгие правила, что можно менять внутри одной версии.
Версия в пути
Основная версия — в адресе: https://api.slicer.media/v1. Внутри /v1 изменения только добавляющие:
- новые эндпоинты;
- новые необязательные поля в запросах и новые поля в ответах;
- новые значения в конце перечислений (например, новый статус публикации или новый шрифт в каталоге);
- новые события вебхуков и новые коды ошибок.
Удалить поле, переименовать его, поменять смысл или тип, сделать необязательное поле обязательным — это несовместимое
изменение. Оно возможно только в /v2, и после её выхода /v1 продолжает работать не меньше 12 месяцев.
Номер спецификации
Спецификация API — GET /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 публикуется в журнале изменений с меткой «Изменение 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), например ролик до пересборки (Версии ролика) |
1.9.0 | 27.10.2026 | Переход «Звук раньше»: вид jcut в переходах операций tune_block и set_all_transitions, длительность — от 0,15 до 1 с (Переходы) |
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" ставит каждую фразу туда, где в кадре больше свободного места (Стиль) |
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"). Свой режиссёр: 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 | Первая версия: загрузки, монтаж с подтверждением цены, три версии ролика, правки операциями, ИИ-помощник, перевод, стиль, экспорт и публикация, вебхуки |
Подробности каждой версии — в журнале изменений.
Как писать устойчивый клиент
- Игнорируйте незнакомые поля в ответах и вебхуках — новые поля появятся без предупреждения.
- Будьте готовы к новым значениям перечислений. Если пришёл неизвестный
statusили тип события, обработайте его как «прочее», а не падайте. Пример — статусdraft, появившийся в1.1.0. - Не полагайтесь на порядок полей в JSON и на точный текст
message— только наcode. - Отправляйте только нужные поля. Неизвестные поля в теле запроса сервер отбрасывает; опечатка в имени поля не вызовет ошибку, но и не сработает — сверяйтесь со справочником.
- Документ монтажа (
GET /v1/projects/{id}/document) — внутренняя модель ролика, в v1 в ней тоже только добавляются поля. Для правок надёжнее операции: они не зависят от устройства документа.
Генерация клиента
Спецификацию можно отдать генератору клиентов — например, openapi-typescript для TypeScript или
openapi-python-client для Python:
npx openapi-typescript https://api.slicer.media/v1/openapi.json -o slicer-api.d.tsСпецификация доступна без токена. Справочник этой документации строится из неё же, поэтому документация и сервер не расходятся.