ГлавнаяДокументацияСправочник API
🔌Справочник APIпрокси, совместимый с v1

Подключайте любой совместимый клиент к единому API прокси

Эта страница описывает публичные маршруты, для моделей каталога OmniRouter с оплатой из баланса Omni Credits. Форматы тел следуют Anthropic и OpenAI API; Omni Router добавляет авторизацию, выбор интерфейса, лимиты и учёт использования.

Машиночитаемый контракт: OpenAPI 3.1 JSON. Каждая операция содержит стабильный operationId, типизированные поля, схему JSON‑ошибки и обозначение требуемого разрешения клиентского ключа.

Базовый URL

https://api.omnirouter.ru

Интерфейсы API

Anthropic · Responses · Chat · MCP

Секреты

Только omni_ токен

01 · Подключение

Базовый URL

Все публичные запросы идут на API-домен. Anthropic-клиенты используют URL без /v1: клиент сам добавит этот путь. OpenAI-клиенты обычно получают базовый URL с /v1.

Anthropic base_urlhttps://api.omnirouter.ru
OpenAI base_urlhttps://api.omnirouter.ru/v1

02 · Безопасность

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

Интерфейс Anthropic

x-api-key
x-api-key: omni_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Используется для /v1/messages, /v1/models и /v1/messages/count_tokens.

Интерфейсы OpenAI

Bearer
Authorization: Bearer omni_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Используется для Responses, Chat Completions и транскрипции. Для совместимости обработчик также принимает omni-токен в x-api-key.

Храните токен как секрет. Не передавайте его в браузерный JavaScript, URL, логи или публичные репозитории. Поддерживаются только ключи omni_; устаревший формат prx_ не принимается.
Область разрешений. Клиентский ключ даёт доступ только к получению списка моделей и явно документированным операциям генерации, поиска, изображений, аудио и MCP. Он не авторизует API личного кабинета, управление аккаунтом или удалённый доступ к окружению агента программирования. Подробнее: безопасность ключей.

03 · Маршрутизация

Интерфейсы API

Omni Credits поддерживают Messages, Responses и Chat Completions для текстовой генерации. Используйте точный MODEL_ID из GET /v1/models. Непредставимые поля или возможности возвращают 400; поля и аргументы инструментов не удаляются молча.

Совместимый с Anthropic

Omni Credits

x-api-key: omni_…/v1/messages · /v1/models · /v1/messages/count_tokens
OpenAI Responses

Omni Credits

Authorization: Bearer omni_…/v1/responses · /v1/responses/compact
OpenAI Chat

Omni Credits

Authorization: Bearer omni_…/v1/chat/completions
Credits и MCP

Omni Credits

Authorization: Bearer omni_…/v4/ai/evaluation-model · /v1/search · /v1/images/generations · /mcp

Модели не фиксируются этой страницей: доступный список зависит от подключённого аккаунта внешнего провайдера, его плана и текущего лимита. Для токена, поддерживающего этот маршрут, используйте GET /v1/models.

Кэширование текста с Omni Credits

Для поддерживаемых моделей OmniRouter автоматически запрашивает кэширование промпта. Если он добавляет явный маркер, срок его действия — пять минут. Отправьте X-OmniRouter-Prompt-Cache: off, чтобы отключить добавление таких управляющих полей для конкретного запроса. Заголовок auto или его отсутствие оставляет поведение по умолчанию.

Заголовок не задаёт срок хранения. Если модель поддерживает более долгий кэш, в запросе Messages можно явно указать cache_control с ttl: "1h". Значение off сохраняет такие правила и не отключает кэширование, которое модель выполняет самостоятельно. Другие значения заголовка возвращают 400. Попадание в кэш не гарантируется; скидка на чтение применяется только к подтверждённым токенам чтения из кэша.

04 · Совместимость с Anthropic

Anthropic API

Omni Router сохраняет формат запроса и ответа Anthropic, включая обычный режим и потоковую передачу SSE. Дополнительные поля внешнего провайдера могут передаваться дальше.

POST/v1/messagesAPI сообщений

Основной маршрут для Claude Code и Anthropic-совместимых клиентов. Обязательные поля: model, max_tokens и messages.

Передавайте сообщения, инструменты и результаты в формате Messages. Поддержка конкретных возможностей зависит от выбранной модели; непредставимые поля возвращают 400.

Поля тела

model
строка, обязательно
max_tokens
целое число, обязательно
messages
массив, обязательно
stream
логическое, по умолчанию false
tools
массив, необязательно

При stream: true ответ содержит события message_start, события блоков содержимого, message_delta и message_stop.

Пример

curl -N https://api.omnirouter.ru/v1/messages \
  -H "x-api-key: omni_***" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 256,
    "stream": true,
    "messages": [{"role": "user", "content": "Привет"}]
  }'
GET/v1/modelsСписок моделей

Без ключа возвращает публичный каталог Omni Credits. С ключом Credits — тот же каталог; с ключом подключения — модели этого подключения. Передайте ключ через Authorization: Bearer или x-api-key. Неверный ключ возвращает ошибку авторизации.

Формат одинаковый для всех подключений: ID модели находится в data[].id. Для пагинации используйте limit, after_id и before_id. При has_more: true передайте last_id в after_id следующего запроса. Наличие модели в списке не подтверждает достаточный баланс, квоту или доступ к генерации изображений.

Расширенный публичный каталог с возможностями моделей и ценами в рублях доступен без ключа по /api/public/models.

{
  "object": "list",
  "data": [{
    "id": "example-model",
    "object": "model",
    "type": "model",
    "display_name": "Example Model"
  }],
  "has_more": false,
  "first_id": "example-model",
  "last_id": "example-model"
}
POST/v1/messages/count_tokensПодсчёт токенов

Принимает поля model и messages в формате Anthropic и возвращает количество входных токенов. Поддержка зависит от внешнего провайдера.

// request
{"model":"MODEL_ID","messages":[{"role":"user","content":"Привет"}]}

// ответ
{"input_tokens": 8}

05 · Совместимость с OpenAI

Responses и Chat Completions

Для клиентов в стиле OpenAI используйте Bearer omni-токен и базовый URL с /v1. Алиасы без /v1 оставлены для клиентов, которые добавляют путь самостоятельно.

POST/v1/responsesтакже доступен: /responses

OpenAI Responses API для Codex и совместимых SDK с оплатой из баланса Omni Credits. Поддерживаются обычная генерация и SSE. Передавайте историю в input; непредставимые поля и инструменты отклоняются с ошибкой 400.

Совместимость

  • •model и input передаются в формате Responses.
  • •Внешнему Codex обычно нужны instructions и store: false.
  • •Для изображений используйте /v1/images/generations, для поиска — /v1/search.

Пример

curl -N https://api.omnirouter.ru/v1/responses \
  -H "Authorization: Bearer omni_***" \
  -H "content-type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "instructions": "You are a helpful assistant.",
    "input": "Привет!",
    "store": false,
    "stream": true
  }'
POST/v1/responses/compactтакже доступен: /responses/compact

Компактный маршрут Responses для клиентов, которые явно используют компактный формат обмена. Аутентификация и проверка интерфейса такие же, как у /v1/responses.

POST/v1/chat/completionsтакже доступен: /chat/completions

Интерфейс OpenAI Chat Completions для Omni Credits. Для Credits запрос переводится fail-closed в Messages, сохраняя представимые сообщения, reasoning, function tools, результаты инструментов, usage и streaming; непредставимые поля возвращают 400.

curl -N https://api.omnirouter.ru/v1/chat/completions \
  -H "Authorization: Bearer omni_***" \
  -H "content-type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "stream": true,
    "messages": [{"role": "user", "content": "Привет"}]
  }'

Распознавание речи

POST /v1/audio/transcriptions

Используйте ключ Omni Credits, достаточный баланс и стабильный Idempotency-Key. Multipart-запрос содержит file (WAV, до 25 МиБ и 20 минут), точный идентификатор модели распознавания в model и response_format=json. Ответ содержит текст. Повторяйте ключ идемпотентности только с тем же запросом.

07 · Credits и инструменты

Изображения, поиск и MCP

POST/v4/ai/evaluation-model

AI SDK v4 Evaluation API для typesafe-ai/jev. Передайте модель в ai-model-id, версию 4 в ai-evaluation-model-specification-version, общее state и до 128 вопросов Choice, Score или Boolean. Нужны ключ Omni Credits и уникальный Idempotency-Key; результат безопасно повторяется 15 минут. Максимальный JSON-запрос — 512 КиБ.

curl https://api.omnirouter.ru/v4/ai/evaluation-model \
  -H "Authorization: Bearer omni_***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: eval-$(uuidgen)" \
  -H "ai-model-id: typesafe-ai/jev" \
  -H "ai-evaluation-model-specification-version: 4" \
  -d '{"state":"A full refund was issued.","questions":{"refunded":{"type":"boolean","instructions":"Was a refund issued?"}}}'
POST/v1/images/generations

С ключом Omni Credits укажите source: credits. Доступность возвращает GET /v1/images/sources, модели — GET /v1/images/models?source=credits.

Для генерации нужен достаточный баланс и стабильный Idempotency-Key. Ответ 202 продолжайте через GET /v1/images/generations/{job_id}, затем скачайте изображение по защищённому URL с тем же ключом.

Хранилище и автоудаление

Управляйте файлами на странице аккаунта или через API. Бесплатная квота — 5 ГиБ. Все запросы ниже требуют ваш OmniRouter API-ключ в Authorization: Bearer и доступны только для файлов вашего аккаунта.

  • GET /v1/storage — квота, использование и срок хранения
  • GET /v1/storage/assets — список файлов
  • GET /v1/storage/assets/{id}/content — скачивание
  • DELETE /v1/storage/assets/{id} — удаление
  • GET /v1/storage/policy — текущая настройка
  • PATCH /v1/storage/policy — изменение настройки
  • POST /v1/storage/cleanup — массовая очистка

Для автоудаления через три дня отправьте PATCH с JSON {"retention_days":3}. Срок единый для новых API-медиа, референсов и файлов сайта, отсчитывается от подготовки запроса; активные задания защищены до завершения. Допустимый максимум возвращается в max_retention_days. Существующие даты сохраняются; явное apply_to_existing:true сокращает их и может немедленно удалить старые файлы.

Список возвращает data, has_more и next_cursor. Передайте курсор как after; limit — от 1 до 200. Каждый файл содержит ID, имя, размер, источник, виртуальную папку, дату удаления и признак protected.

Предпросмотр очистки: {"asset_ids":["ID"],"dry_run":true} (до 100 ID). Для удаления передайте dry_run:false. Удаление необратимо и отключает ссылки в связанных диалогах. Ответ 202 pending означает очередь повторной очистки; место освобождается после успешного удаления. Очистка запускается каждые пять минут. Активные файлы пропускаются; DELETE для них возвращает 409.

После удаления всех изображений задания его повтор или опрос возвращает 410 image_result_deleted, без новой генерации и списания в пределах окна идемпотентности. Настройка удаляет файлы, а не историю оплаты или все данные аккаунта.

MCPPOST /mcp

Stateless Streamable HTTP MCP: list_models, search, image_sources, list_image_models, generate_image, get_image_generation и download_image. Для генерации выберите модель из каталога и передайте source: credits. Запросы оплачиваются из баланса Omni Credits. Настройка клиента и правила оплаты →

08 · Служебные маршруты

Установщики

GET/install/claude.sh/install/claude.ps1, /install/codex.sh и /install/codex.ps1

Публичные установочные скрипты для Bash и Windows PowerShell. Они запрашивают omni-ключ интерактивно и сохраняют готовую конфигурацию локально. Для подробностей откройте инструкцию по Claude Code или инструкцию по Codex; не передавайте omni-ключ в URL.

curl -fsSL https://api.omnirouter.ru/install/claude.sh | bash
irm https://api.omnirouter.ru/install/claude.ps1 | iex
curl -fsSL https://api.omnirouter.ru/install/codex.sh | bash
irm https://api.omnirouter.ru/install/codex.ps1 | iex
Не входят в клиентский API: управляющие маршруты личного кабинета /api/*, обратные вызовы OAuth, /webhooks/yookassa и /payment/complete обслуживают внутренние или сценарии конкретных провайдеров и не являются частью этого справочника.

09 · Надёжность

Ошибки, повторные запросы и ограничения частоты

При временных ошибках используйте экспоненциальную задержку. Заголовок retry-after, если он присутствует, имеет приоритет над локальным значением по умолчанию.

401

Неавторизован

Токен отсутствует, имеет неверный формат, деактивирован.

400

Неверный запрос

Неверное тело запроса или токен используется на несовместимом интерфейсе API.

429

Слишком много запросов

Достигнут лимит пользователя или внешний провайдер вернул ограничение частоты. Используйте retry-after.

502

Ошибка шлюза

Прокси не смог подключиться к внешнему провайдеру или прочитать его ответ. Это не означает, что внешний провайдер вернул HTTP 502.

503

Сервис недоступен

Прокси временно не готов обслуживать запрос. Повторите его с задержкой.

500

Внутренняя ошибка

Внутренняя ошибка прокси или базы данных. Не повторяйте запрос бесконечно; при устойчивой ошибке обратитесь в поддержку.

Нужна пошаговая настройка?

Инструкции для клиентов не смешаны со справочником и объясняют настройку от начала до первого запроса.

Вернуться к инструкциям