Версия зашита в путь: /api/v1. Пока в пути стоит v1, ломающих изменений в нём не будет — новое поведение приходит новыми полями, а не переименованием старых.
400, стало 422.Всё это выйдет только в /api/v2, и /api/v1 продолжит работать. Дата отключения старой версии объявляется не позднее чем за шесть месяцев — письмом на адрес аккаунта и заголовком X-Api-Deprecated в каждом ответе.
| Изменение | Почему это безопасно |
|---|---|
| Новое необязательное поле в ответе | Клиент, который его не читает, не замечает. |
| Новый необязательный параметр запроса | Умолчание совпадает с прежним поведением. |
| Новая модель в каталоге | Существующие идентификаторы не трогаются. |
| Новая площадка под существующей моделью | Идентификатор и формат ответа те же, меняется только маршрут. |
| Изменение текста в error.message | Ветвиться нужно по error.code, он стабилен. |
| Порядок ключей в JSON | Порядок в JSON не значим — если ваш парсер на него смотрит, это баг парсера. |
Цена не часть контракта API и меняется вслед за первоисточником и курсом. Мы не меняем цену задним числом: списание считается по тарифу на момент запроса, и в логе активности видно, по какому именно. История изменений — на карточке модели, методика — на странице сравнения цен.
Если воспроизводимость важнее свежести, фиксируйте три вещи явно: точный идентификатор модели без плавающих алиасов, площадку через блок provider и версию API в адресе.
{
"model": "anthropic/claude-sonnet-5-20260514",
"provider": {
"order": ["anthropic"],
"allow_fallbacks": false
}
}Такой запрос либо отработает ровно так же, как вчера, либо вернёт 502. Это осознанный размен: при allow_fallbacks: false мы не подставим другую площадку ради того, чтобы ответ хоть какой-то, но был.