Как перенести проект с официального API на шлюз

Совместимый шлюз говорит на том же протоколе, что и официальный API, поэтому переезд обычно не требует изменений в коде. Меняется конфигурация, а не логика.

Что меняется

Ровно две вещи: адрес и ключ.

- ANTHROPIC_BASE_URL=https://api.anthropic.com
- ANTHROPIC_API_KEY=sk-ant-...
+ ANTHROPIC_BASE_URL=https://api.zukko.pro
+ ANTHROPIC_AUTH_TOKEN=fetch_...

Для OpenAI SDK аналогично, только адрес с суффиксом /v1:

- OPENAI_BASE_URL=https://api.openai.com/v1
+ OPENAI_BASE_URL=https://api.zukko.pro/v1
- OPENAI_API_KEY=sk-...
+ OPENAI_API_KEY=fetch_...

Что не меняется

Сам SDK остаётся тот же, версию менять не нужно. Структура запросов, работа с инструментами, потоковая передача, обработка ошибок — всё как было. Код, который вызывает модель, трогать не придётся.

Что проверить обязательно

Имена моделей. Это главный источник сюрпризов. Идентификаторы у шлюза могут отличаться от официальных. Посмотрите каталог до переезда:

curl -s https://api.zukko.pro/v1/models

Если в коде зашито имя, которого в каталоге нет, получите 404 при первом же вызове.

Переменную ANTHROPIC_API_KEY. Её нужно убрать полностью, а не оставить пустой. Иначе клиенты Anthropic будут считать, что вы работаете напрямую, и часть из них попросит логин.

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

Порядок переезда

Начните с одного некритичного окружения — локального или стейджинга. Прогоните на нём обычную рабочую задачу целиком, а не один тестовый запрос: короткий запрос не покажет проблем с длинным контекстом, инструментами и стримингом.

Сравните результат с тем, что давал официальный API на той же задаче. Не только «ответ пришёл», а качество и формат: если код разбирает ответ по структуре, важно, чтобы структура совпала.

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

Только после этого переключайте прод. Откат при этом стоит ровно столько же, сколько переезд: вернуть две строки конфигурации.

Чего ожидать по деньгам

Экономия возникает на разнице тарифов, а не на объёме — токенов вы будете тратить столько же. Прикиньте по своей реальной нагрузке: возьмите месячный расход в токенах из истории и умножьте на новый тариф. Это точнее любых обещаний в процентах.