Основные понятия

Слаги моделей, стандартный интерфейс chat completion и детали, которые скрывает шлюз.

Основы

Для работы достаточно простой модели происходящего. Для вашего кода ToyGate выглядит как стандартный API, но внутри переводит запрос и проксирует его тому upstream-провайдеру, который обслуживает выбранную модель. Четыре понятия ниже объясняют остальную документацию.

Слаг модели определяет маршрут

Поле model в запросе содержит слаг — короткий понятный человеку id, которым управляет шлюз. Примеры: gpt-5.5, claude-opus-4-8. Полный список приведён на странице моделей.

Клиент всегда работает только со слагами. Шлюз сам сопоставляет слаг реальной upstream-модели. Если оператор переключит gpt-5.5 на другого провайдера или новый snapshot, клиентский код менять не потребуется.

your request → "model": "gpt-5.5"
↓
gateway resolves the slug
↓
standard API request to the upstream
↓
gateway translates the response back to standard shape
↓
your client gets the response it expects

Стандартный API на входе и выходе

Публичный API использует стандартный протокол chat/completions. Обычные и потоковые ответы, function calling и vision-запросы для моделей с поддержкой изображений работают после замены только baseURL и API key.

Даже если upstream использует другой формат, например Anthropic /v1/messages, шлюз переводит запрос и ответ в обе стороны. На проводе клиент всегда видит стандартный формат.

Upstream намеренно скрыт

По ответу нельзя определить, какой провайдер фактически выполнил запрос:

Поле model повторяет запрошенный слаг, а не внутренний id upstream.
Поле owned_by в каталоге задаёт оператор шлюза, например direct request для self-hosted модели или название партнёра.
Ошибки используют стабильные коды, определённые шлюзом. Исходные ошибки upstream клиенту не передаются.

Такая изоляция позволяет оператору менять провайдеров без поломки интеграций. Не пытайтесь определять upstream по форме ответа: она может измениться без предупреждения.

Чего шлюз не делает

Некоторые функции явно не входят в текущую область:

Не кеширует ответы. Каждый запрос доходит до upstream. Если нужно кеширование, реализуйте его в клиенте или CDN для общедоступного read-only трафика.
Не смешивает провайдеров внутри запроса. Один слаг ведёт к одному upstream. Если нужен fallback для отдельного запроса, реализуйте его в клиенте через разные слаги.
Пока не принимает запросы structured output. Поле response_format приводит к HTTP 400 с error.code = "response_format_not_supported". На это же неподдерживаемое поле опираются вспомогательные функции вроде generateObject из Vercel AI SDK.
Не отбрасывает изображения молча. Части image_url передаются upstream, если выбранная модель поддерживает vision. Для модели без такой возможности шлюз возвращает HTTP 400 с error.code = "model_does_not_support_images".

Если поведение кажется неожиданным, причина обычно связана с одним из этих четырёх принципов.