Base URL с /v1 или без — куда какой адрес

Самая частая ошибка при подключении к любому API-шлюзу — суффикс /v1 в базовом адресе. Она даёт 404, причём формулировка ответа не подсказывает причину, и люди по полчаса ищут проблему в ключе.

Почему клиенты ведут себя по-разному

Всё дело в том, что каждый клиент считает «базовым адресом».

SDK Anthropic и построенный на нём Claude Code считают базой корень сервиса и сами дописывают /v1/messages. Дадите им адрес с /v1 — получите /v1/v1/messages.

OpenAI SDK и всё, что на нём построено (Cursor, Codex, множество IDE-расширений), считают базой уже версионированный префикс и дописывают только /chat/completions. Дадите им адрес без /v1 — получите /chat/completions в корне.

Обе ошибки выглядят одинаково: 404 от сервера, который просто не знает такого пути.

Таблица

Правило, которое проще запомнить: если клиент называет себя Anthropic-совместимым — без /v1, если OpenAI-совместимым — с /v1.

Как распознать ошибку

Сделайте запрос и посмотрите на код ответа.

404 с текстом про несуществующий путь — почти наверняка суффикс. Проверьте адрес.

404 с текстом про модель (The model ... does not exist) — адрес правильный, вы дошли до сервиса, но просите модель, которой нет в каталоге. Это уже другая проблема.

401 — адрес правильный, дело в ключе.

То есть по тексту 404 можно отличить одну ошибку от другой, не гадая.

Быстрая проверка адреса

curl -s -o /dev/null -w "%{http_code}\n" https://api.zukko.pro/v1/models

Ответ 200 означает, что сервис доступен и версионированный префикс — это /v1. Дальше остаётся решить, дописывает ваш клиент этот префикс сам или нет: посмотрите в его документацию или просто попробуйте оба варианта, это занимает минуту и ничего не стоит.