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

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

Что мы считаем совместимымСкопировать ссылку на раздел

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

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

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

Ломающие измененияСкопировать ссылку на раздел

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

Устаревшие поляСкопировать ссылку на раздел

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

Версии SDKСкопировать ссылку на раздел

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

Статус сервисаСкопировать ссылку на раздел

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