---
title: Версии и совместимость
description: Clipia API развивается в одной версии /v1 — какие изменения считаются совместимыми, что попадает в changelog, устаревшие поля и версии SDK.
icon: GitBranch
---

Публичный API живёт по адресу `/v1/*`, и это единственная текущая версия. Мы развиваем контракт без смены номера и записываем заметные изменения в [changelog](/ru/docs/changelog). Политика версий ещё уточняется: сроков предупреждения об изменениях и отдельной версии пути пока нет.

## Что мы считаем совместимым

Такие изменения выходят без предупреждения и не меняют версию пути. Клиент должен переносить их без правок кода:

- новые эндпоинты и новые необязательные параметры запросов;
- новые поля в ответах, в объектах `output`, `warnings` и `error`;
- новые значения `warnings[].code` и новые `code` ошибок внутри существующих HTTP-статусов;
- новые модели в каталоге и новые параметры `input` у моделей — они описаны в `input_schema` модели;
- изменение текста `message`: он предназначен для человека.

Отсюда два правила для интеграции: игнорируйте неизвестные поля и ветвите логику по `code` и `status`, а не по тексту сообщения. Клиенты, которые ждут терминальный статус, зависят от полного списка значений `status`, поэтому новое значение мы считаем ломающим изменением, как и новый `type` ошибки.

## Ломающие изменения

Ломающим считается удаление или переименование эндпоинта, поля или параметра, смена типа или смысла поля, удаление значения `status` или кода ошибки, смена схемы аутентификации. Такое изменение мы отмечаем в [changelog](/ru/docs/changelog).

## Устаревшие поля [#deprecated]

Поле помечается устаревшим, когда оно больше не несёт смысла, но остаётся в ответах ради совместимости. Удаление устаревшего поля — ломающее изменение.

| Поле | Где | Сейчас | Что использовать вместо |
|------|-----|--------|-------------------------|
| `queue_position` | ответы [отправки](/ru/docs/api-reference/submit) и [статуса](/ru/docs/api-reference/status) | всегда `0`: позиция в очереди не считается | `status` и `progress` |

## Версии SDK

Официальные клиенты — TypeScript [`clipia-ai`](/ru/docs/sdk/typescript) на npm и Python [`clipia`](/ru/docs/sdk/python) на PyPI — версионируются по semver и выходят с одинаковым номером: новое поле, опция или метод — minor, исправление — patch, удаление или смена типа — major. История — в changelog пакетов и в [changelog портала](/ru/docs/changelog). Версия MCP-сервера ведётся отдельно и видна в его метаданных.

## Статус сервиса [#status]

Отдельной страницы статуса и соглашения об уровне сервиса (SLA) у публичного API сейчас нет. С вопросами о сбоях обращайтесь в поддержку: support@clipia.ai и Telegram [@clipia_support](https://t.me/clipia_support). Если запрос вернул `503 service_unavailable` или `500 internal_error`, повторите его с растущей паузой по правилам страницы [«Ошибки»](/ru/docs/api-reference/errors); кредиты за несостоявшуюся генерацию не списываются.