Справочник API
Базовые URL, аутентификация, соглашения о запросах, лимиты и рекомендации по повторам, общие для всех эндпоинтов Lovely Router.
Lovely Router обслуживает с одного хоста, с одним ключом и одним балансом два вида API:
- API моделей в собственных форматах вендоров: Anthropic Messages, OpenAI Chat Completions и Gemini. Запросы и ответы соответствуют справочнику API вендора, поэтому официальные SDK работают без изменений. Lovely Router добавляет лишь несколько заголовков ответа.
- API Lovely Router для инструментов данных (
/v1/tools) и браузерного агента (/v1/browser): JSON API, следующие соглашениям, описанным ниже.
Messages, Chat Completions, Gemini, подсчёт токенов и список моделей.
Поиск по каталогу, запуск инструментов и получение результатов.
Запуск браузерного агента и управление им, а также секреты, файлы и профили.
Превратите песню в музыкальный клип, просмотрите его сцены и скачайте результат.
Коды статуса, тела ошибок и политика повторов.
Базовые URL#
Все эндпоинты обслуживаются по HTTPS с https://lovelyrouter.com.
| API | Базовый URL SDK | Эндпоинты |
|---|---|---|
| Anthropic Messages | https://lovelyrouter.com | POST /v1/messages, POST /v1/messages/count_tokens |
| OpenAI Chat Completions | https://lovelyrouter.com/v1 | POST /v1/chat/completions |
| Gemini | https://lovelyrouter.com | POST /v1beta/models/{model}:generateContent, :streamGenerateContent, :countTokens |
| Список моделей | — | GET /v1/models, GET /v1beta/models |
| Инструменты данных | https://lovelyrouter.com/v1 | /v1/tools/... |
| Браузерный агент | https://lovelyrouter.com/v1 | /v1/browser/... |
| Музыкальные клипы | https://lovelyrouter.com/v1 | /v1/videos/music/... |
| MCP-сервер | — | POST /mcp |
Эндпоинты, которых нет в этом списке, например Responses, Embeddings и Images API от OpenAI, возвращают 404.
Аутентификация#
Передавайте API-ключ как bearer-токен. Эндпоинты моделей принимают и собственные заголовки вендоров, поэтому каждый SDK работает с настройками по умолчанию.
Authorization: Bearer lr-...| Заголовок | Типичное применение |
|---|---|
Authorization: Bearer lr-... | OpenAI SDK, инструменты данных, браузерный агент, MCP |
x-api-key: lr-... | Anthropic SDK |
x-goog-api-key: lr-... | Google Gen AI SDK |
Списку моделей и каталогу инструментов ключ не нужен. Всему остальному нужен. См. Аутентификация.
Запросы и ответы#
- JSON на входе и на выходе. Отправляйте тела запросов в JSON с
content-type: application/json. Исключения — загрузка файлов для браузерного агента, которая принимает «сырой» файл илиmultipart/form-data, и скриншоты запусков, которые возвращаются какimage/jpeg. - Потоковая передача. Запросы Anthropic и OpenAI с
"stream": trueвозвращают серверные события (text/event-stream).:streamGenerateContentв Gemini отдаёт потоковый JSON-массив или серверные события с?alt=sse, как и API Google. См. Потоковая передача. - Кросс-доменные запросы разрешены с любого origin. Но это не значит, что вызывать API из браузера безопасно: ключ во фронтенд-коде может прочитать кто угодно.
Собственные API Lovely Router следуют таким соглашениям:
| Соглашение | Пример |
|---|---|
| У id есть префикс типа | run_… для запусков инструментов, brun_… для запусков браузера |
| Метки времени в ISO 8601, UTC | "created_at": "2026-10-11T09:30:00.000Z" |
| Суммы в долларах США, числами | "charge_usd": 0.042, "reserved_usd": 0.3 |
| Списки обёрнуты в объект | {"object": "list", "data": [...]} |
Долгая работа возвращает 202 | В теле есть путь poll для проверки статуса |
| Ожидание задаётся параметром запроса | GET /v1/tools/runs/{id}?wait=60 удерживает запрос, пока запуск не завершится или не истечёт время |
Заголовки ответа#
Помимо заголовков вендора, ответы моделей содержат:
| Заголовок | Значение |
|---|---|
x-lovely-request-id | Уникальный id запроса, он же показан в Логах. Указывайте его, когда обращаетесь в поддержку. |
x-lovely-group | Группа каналов, обслужившая запрос |
x-lovely-channel | Краткое описание этой группы каналов в URL-кодировке |
x-lovely-queued-ms | Сколько миллисекунд запрос ждал ёмкости, если ему пришлось ждать |
retry-after | В ответах 429: сколько секунд подождать перед повтором |
Версионирование#
API моделей следуют версионированию вендора. Отправляйте те заголовки, которые отправляет ваш SDK: anthropic-version и anthropic-beta для Anthropic, openai-beta для OpenAI. Запросы Gemini используют путь /v1beta, как и API Google. Lovely Router пересылает эти заголовки и никакие другие, поэтому функции, зависящие от иного заголовка вендора, недоступны.
API Lovely Router версионируются по пути и находятся под /v1. В ответах могут появляться новые поля, поэтому пишите клиенты так, чтобы они игнорировали незнакомые поля.
Лимиты запросов#
К вашим запросам применяются такие лимиты:
| Лимит | К чему применяется | При превышении |
|---|---|---|
| Запросы в минуту и параллелизм, заданные для ключа | Запросы к моделям с этим ключом | 429 с retry-after |
| Ёмкость модели | Запросы к моделям. Короткие всплески сначала несколько секунд ждут в очереди. | 429, обычно с retry-after |
| 10 одновременных запусков на аккаунт | Запуски инструментов данных и браузера | 429 |
| 100 запросов в минуту на ключ; 100 в минуту на всех вызывающих без ключа вместе | POST /v1/tools/suggest | 429 с retry-after |
См. Лимиты запросов и переключение и API-ключи.
Повторы и идемпотентность#
Прежде чем вернуть ошибку, Lovely Router повторяет неудачные запросы к моделям на других каналах, так что полученный вами 5xx уже был повторён. И всё же стоит повторять ответы 429 и 5xx на своей стороне с экспоненциальной задержкой, учитывая retry-after. Другие ошибки 4xx не повторяйте, не изменив запрос. Официальные SDK OpenAI и Anthropic по умолчанию делают два повтора; для пакетных задач увеличьте max_retries (maxRetries в Node.js).
API не принимает ключи идемпотентности. Учитывайте такие случаи:
- Запрос к модели, у которого истёк таймаут на вашей стороне, мог всё же завершиться и быть оплачен. Повторив его, вы можете заплатить дважды. Задавайте щедрые клиентские таймауты для долгих генераций или используйте потоковую передачу.
- Старт запуска инструмента или браузера не идемпотентен. Если у
POST /v1/tools/{id}/runилиPOST /v1/browser/runsистёк таймаут, проверьте последние запуски черезGET /v1/tools/runsилиGET /v1/browser/runs, прежде чем начинать новый. - Чтение всегда безопасно повторять. Опрос запуска, получение списка запусков и результатов никогда не тарифицируются.
Код повторов на Python и Node.js есть в разделе Повтор неудачных запросов.
Ошибки#
Эндпоинты моделей возвращают ошибки в формате вендора, поэтому SDK выбрасывают привычные исключения. Собственные API Lovely Router возвращают:
{"error": {"type": "invalid_request_error", "message": "\"goal\" is required (max 4,000 characters)"}}Все коды статуса с примерами тел для каждого формата — в разделе Ошибки.