Как работает шлюз

Lovely Router поддерживает API Anthropic, OpenAI и Gemini на одном хосте. Шлюз не переводит запросы из одного формата в другой: запрос в формате Anthropic уходит в канал, который принимает формат Anthropic, а тело запроса доходит до канала в том виде, в каком вы его написали, за исключением двух небольших изменений. Если вызывать модель через API её собственного вендора, она получит запрос ровно так, как описано в документации вендора. Параметры вроде thinking, cache_control, tools или generationConfig доходят до модели без изменений, поэтому действует документация самого вендора.

Эндпоинты и базовые URL#

Укажите в SDK базовый URL для его API. Путь SDK добавит сам.

Остальные эндпоинты моделей возвращают 404. См. раздел что недоступно. API инструментов данных и браузерного агента работают на том же хосте с теми же ключами.

Какой API у каждой модели#

У каждой модели есть родной API — формат, под который её спроектировал вендор. По возможности используйте его.

Если вызвать модель в другом формате, канал преобразует запрос для модели, поэтому часть возможностей вендора может потеряться. Параметры конкретного вендора определены для его собственного API. Anthropic cache_control и thinking, OpenAI reasoning_effort и Gemini thinkingConfig гарантированно работают только в родном формате модели; в другом формате их могут проигнорировать или отклонить.

Какие форматы принимает модель, зависит от обслуживающих её каналов, так что набор может меняться. Маркетплейс показывает их для каждой модели. Если ни один канал не принимает ваш формат, запрос завершается ошибкой 404 с сообщением вроде Model 'gpt-6.1-sol' is not served in gemini format in any group.

Идентификаторы моделей#

Используйте идентификаторы из GET /v1/models, например claude-sonnet-5.5, gpt-6.1-sol или gemini-3.1-pro. Шлюз также принимает варианты написания, которые используют другие инструменты, и сопоставляет их с той же моделью:

Правила такие: регистр не учитывается, начальный префикс vendor/ или models/ отбрасывается, . и - взаимозаменяемы, а дата в конце (-20251001), -preview или -latest отбрасываются. В логах, списках разрешённых моделей ключа и при биллинге всегда используется канонический идентификатор.

Идентификатор, который не соответствует ни одной модели, возвращает 404 с сообщением Model '<id>' is not available. See GET /v1/models.

Что меняет шлюз#

Тело запроса пересылается так, как вы его отправили, с двумя исключениями:

1. Идентификатор модели. Он заменяется на тот, который ожидает обслуживающий канал. Поэтому поле model в ответе может содержать написание вендора, например claude-sonnet-5-5.
2. Usage в потоках OpenAI. К потоковым запросам Chat Completions добавляется stream_options.include_usage: true, чтобы шлюз мог выставить счёт за вызов. Ваш поток заканчивается одним дополнительным чанком с пустым массивом choices и объектом usage. При чтении чанков учитывайте, что choices может быть пустым.

Заголовки запроса не пересылаются, кроме anthropic-version, anthropic-beta и openai-beta. Если anthropic-version отсутствует, отправляется 2023-06-01. На эндпоинтах Gemini query-параметры вроде alt=sse пересылаются, а key удаляется.

Ответы возвращаются байт в байт. Шлюз сохраняет заголовки content-type и cache-control и добавляет свои (см. заголовки ответа). Идентификаторы запросов вендора и заголовки лимитов запросов не передаются.

Если модель отклоняет запрос как некорректный (400, 404, 413, 422), вы получаете тот же статус и причину в формате ошибок вашего API. При остальных сбоях запрос сначала повторяется на другом канале. См. Лимиты запросов и переключение каналов и Ошибки.

Аутентификация#

Каждый эндпоинт принимает ключ в любом из этих мест, поэтому любой SDK работает со своей авторизацией по умолчанию:

GET /v1/models и GET /v1beta/models не требуют ключа. Как обращаться с ключами, см. в разделе Аутентификация.

Заголовки ответа#

Браузеры могут читать первые три: они перечислены в access-control-expose-headers.

Жизненный цикл запроса#

1. Аутентификация. Ключ должен быть активен и не просрочен, иначе вы получите 401.
2. Определение модели. Идентификатор сопоставляется, как описано выше, и проверяется по списку разрешённых моделей ключа (403, если модель не разрешена).
3. Проверка баланса. Если баланс равен нулю или ниже либо ключ превысил лимит расходов, возвращается 402.
4. Применение лимитов ключа. Действуют лимиты ключа на число запросов в минуту и на параллельность (429). См. Лимиты запросов и переключение каналов.
5. Выбор канала. Уже идущий диалог возвращается в канал, где хранится его кеш промпта. Новые диалоги идут в лучший доступный канал группы каналов. См. Кеширование промптов.
6. Вызов модели. Если канал дал сбой до того, как начал выдавать ответ, запрос переходит на другой канал, всего до трёх попыток. Потоки удерживаются до первого токена, поэтому для вас это незаметно. См. Потоковая передача.
7. Учёт и логирование. Сумма списания определяется числом токенов из ответа и списывается с баланса в течение нескольких секунд. См. Модели и цены.

Что недоступно#

Существуют только перечисленные выше эндпоинты. Эти возвращают 404:

• Сохранённые ответы OpenAI (/v1/responses/{id}), устаревший Completions, эмбеддинги, вариации изображений, аудио, файлы и пакетная обработка (batches).
• Эндпоинты Anthropic Message Batches, Files и Models по идентификатору.
• Gemini cachedContents (явное кеширование контекста), загрузка файлов, embedContent и Live API.

OpenAI Responses API доступен только для моделей GPT. В разделе Использование с вашими инструментами есть настройки для популярных клиентов.