Обзор API

RouteAPI предоставляет унифицированный доступ к AI API для организаций, объединяя возможности моделей OpenAI, Claude, Gemini, Azure, AWS Bedrock и других в единой стабильной, наблюдаемой и измеримой системе интерфейсов. Бизнес-системам достаточно подключиться к RouteAPI, чтобы вызывать разные модельные сервисы при единой аутентификации, единых model ID и едином логировании.

Начало работы за три шага

Если вы уже используете любой OpenAI-совместимый SDK, достаточно изменить две настройки, чтобы всё заработало:

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{ "role": "user", "content": "你好" }]
  }'

1. Замените Base URL на https://api.routeapi.ai/v1.
2. Замените API Key на ваш RouteAPI Token (создаётся на странице API Keys в консоли).
3. Замените model на доступный вашей учётной записи model ID — уточните через GET /v1/models.

Полные шаги перехода для уже работающего приложения на OpenAI см. в разделе Миграция с OpenAI.

Поддерживаемые точки входа протоколов

RouteAPI одновременно поддерживает три основных протокола: OpenAI-совместимый, Claude Messages и Google Gemini. Вы можете продолжать использовать существующий SDK или клиент — достаточно переключить Base URL и API Key на RouteAPI.

Протокол	Типичные эндпоинты	Подходящие сценарии
OpenAI-совместимый	/v1/chat/completions, /v1/responses, /v1/embeddings	OpenAI SDK, Cursor, OpenCode, LangChain, LiteLLM и другие совместимые клиенты
Claude Messages	/v1/messages	Claude Code, Anthropic SDK, клиенты с нативным форматом сообщений Claude
Google Gemini	/v1beta/models/{model}:generateContent	Google GenAI SDK, клиенты Gemini REST

Запросы, поступающие через разные протоколы, проходят необходимую адаптацию формата внутри RouteAPI. Со стороны бизнеса лучше выбирать протокол, который текущий клиент поддерживает нативно — нативный протокол не проходит через конвертацию, и его поведение наиболее предсказуемо. Правила маппинга и известные ограничения межпротокольных вызовов (например, вызов модели Claude в формате OpenAI) см. в описании конвертации протоколов.

Базовые адреса

OpenAI-совместимый протокол и Claude Messages по умолчанию используют:

https://api.routeapi.ai/v1

Протокол Google Gemini по умолчанию использует:

https://api.routeapi.ai/v1beta

Общие заголовки запроса

Authorization: Bearer sk-your-routeapi-token
Content-Type: application/json

Все протоколы используют один и тот же тип RouteAPI Token. Храните Token на стороне сервера — не раскрывайте его в браузере, мобильном приложении или публичном репозитории. Подробнее о правах ключей, лимитах и ошибках аутентификации см. в разделе Аутентификация.

Протокол Claude Messages также принимает заголовок x-api-key, привычный для Anthropic SDK, поэтому при использовании Anthropic SDK обычно достаточно изменить только Base URL.

Индекс эндпоинтов и возможностей

Выбирайте точку входа исходя из задачи:

Что я хочу сделать	Какой эндпоинт использовать	Документация
Обычный многошаговый диалог	/v1/chat/completions	Chat Completions
Кодинг-агенты, клиенты новых протоколов	/v1/responses	Responses
Векторный поиск, семантический поиск, RAG	/v1/embeddings	Embeddings
Узнать доступные модели и возможности	/v1/models	Models
Дать модели вызывать внешние функции	параметр tools	Вызов инструментов
Заставить модель выводить данные в фиксированной JSON-структуре	параметр response_format	Структурированный вывод
Передать модели изображение для распознавания	мультимодальный content	Мультимодальный ввод
Потоковый вывод по частям, снижение задержки первого символа	stream: true	Потоковая передача
Генерация музыки с помощью AI	Suno REST API	Suno API

Область совместимости протоколов

RouteAPI старается максимально сохранять нативный опыт вызова каждого протокола, при этом перенаправляя запросы к подходящему модельному сервису. Фактически поддерживаемые возможности зависят от модели, возможностей сервиса и параметров запроса:

Возможность	Описание
Chat Completions	Рекомендуемый базовый API для чата, подходит для большинства клиентов, совместимых с OpenAI SDK
Responses	Подходит для клиентов и кодинг-агентов, поддерживающих протокол OpenAI Responses
Embeddings	Используется для векторного поиска, семантического поиска и RAG
Streaming	Возвращает контент по частям через SSE
Claude Messages	Поддерживает нативную структуру сообщений Claude, подходит для Claude Code и Anthropic SDK
Google Gemini	Поддерживает запросы в стиле Gemini generateContent
Tool Calling	Зависит от того, поддерживает ли модель вызов инструментов
Structured Outputs	Зависит от того, поддерживает ли модель JSON mode или JSON Schema
Vision / Multimodal	Зависит от того, поддерживает ли модель изображения или мультимодальный ввод

Возможности предоставляются на уровне модели, а не платформы: тот же эндпоинт при смене model может потерять поддержку вызова инструментов или ввода изображений. Перед запуском в продакшене протестируйте целевую модель или проверьте поля возможностей, возвращаемые Models.

Условия стабильности API

• Параметры запроса максимально сохраняются и передаются в соответствии с протоколом.
• Если необязательный скалярный параметр явно передан как 0 или false, RouteAPI обрабатывает его как явно заданное значение, а не отбрасывает как значение по умолчанию.
• Параметры, не поддерживаемые конкретной моделью, могут быть адаптированы, проигнорированы или вызвать ошибку — в зависимости от правил совместимости модели.
• В продакшене рекомендуется фиксировать model ID и подготовить стратегию отказоустойчивости для критичных бизнес-процессов.
• Для опциональных возможностей — вызова инструментов, структурированного вывода, визуального ввода и статистики использования при потоковой передаче — рекомендуется сначала проверить их в тестовой среде перед запуском.

Рекомендации по интеграции для организаций

• Оборачивайте RouteAPI Token на стороне сервера, чтобы бизнес-фронтенд не хранил ключ напрямую.
• Используйте разные Token для разных бизнес-систем — это упрощает раздельные лимиты, аудит и диагностику проблем.
• Фиксируйте model ID и пути протоколов — не полагайтесь на временные алиасы или отображаемые имена.
• Логируйте request ID, model ID, код состояния, время выполнения и использование token — это упростит расследование аномалий задержки и стоимости.
• Для ключевых бизнес-процессов включите тайм-ауты потоковой передачи, повторные попытки при сбоях и резервные модели, чтобы снизить влияние сбоя одного модельного сервиса на бизнес.

Что дальше

• Аутентификация — создание Token, настройка лимитов и прав доступа.
• Ошибки и отладка — значения кодов состояния и порядок диагностики.
• Миграция с OpenAI — чек-лист перехода для существующих приложений.
• Интеграция клиентов — конкретные настройки для Cursor, Claude Code, LangChain и других.
• Биллинг и лимиты — статистика использования и принципы биллинга.