Выбор провайдера

RouterAI маршрутизирует запросы к оптимальным провайдерам для вашей модели. По умолчанию выполняется балансировка нагрузки между топ-провайдерами для максимизации аптайма.

Стратегия балансировки

Для каждой модели RouterAI распределяет нагрузку между провайдерами, отдавая приоритет низкой цене.

Узнать, какие параметры (tools, response_format, …) и какие лимиты токенов поддерживает каждый провайдер модели, можно в списке endpoint’ов модели — поля supported_parameters, max_completion_tokens, max_prompt_tokens.

Стандартный алгоритм балансировки нагрузки RouterAI работает следующим образом:

1. Приоритет стабильности: В первую очередь выбираются провайдеры, у которых не наблюдалось значительных сбоев за последние 30 секунд.
2. Выбор по цене: Среди стабильных провайдеров рассматриваются кандидаты с наименьшей стоимостью.
3. Резервные варианты: Оставшиеся провайдеры используются в качестве запасных (fallbacks).

Управление выбором через объект provider

Если стандартное поведение вас не устраивает, передайте объект provider в теле запроса. Поддерживаемые поля:

Идентификаторы провайдеров пишутся в нижнем регистре, например "openai", "anthropic", "google", "deepseek".

Поля работают так же, как в OpenRouter:

1. only и ignore отсеивают провайдеров модели. Если после них никого не осталось, возвращается ошибка 404.
2. order выбирает провайдера среди оставшихся — первого из списка, кто есть.
3. Если никого из order нет: при allow_fallbacks: true (по умолчанию) запрос уходит к первому допустимому провайдеру по умолчанию, при false — ошибка 404.

Например, {"order": ["amazon-bedrock"], "only": ["google-vertex"]} отправит запрос в google-vertex: amazon-bedrock не входит в only и поэтому не рассматривается.

Примечание про резервные попытки. order/only/ignore определяют, какого провайдера RouterAI выберет для обработки запроса. В отдельных случаях — например, при резервной попытке после сбоя провайдера — запрос может быть обработан провайдером вне списка. Жёсткое ограничение даёт country — этот фильтр соблюдается всегда, включая резервные попытки.

Параметры в строке model (@-синтаксис)

Если ваш клиент не поддерживает дополнительные поля в теле запроса (например, некоторые OpenAI-совместимые SDK), часть routing-настроек можно передать прямо в строке model через @-синтаксис:

<model>@<key>=<value>&<key>=<value>

Поддерживаемые параметры:

Значение provider — идентификатор провайдера в нижнем регистре (поле tag в списке endpoint’ов модели), ровно одно значение.

Примеры:

anthropic/claude-opus-5@provider=amazon-bedrock
deepseek/deepseek-v4-pro-0813@allow_fallbacks=false
deepseek/deepseek-v4-pro-0813@provider=deepinfra&allow_fallbacks=false

Как и provider.only в теле запроса, provider — жёсткий выбор: если указанный провайдер не обслуживает модель (или в идентификаторе опечатка), вернётся ошибка 404, а не ответ другого провайдера.

Примечание. @-синтаксис работает только для /v1/chat/completions, /v1/responses и /v1/messages. Embeddings, audio и media не поддерживаются.

Внимание. Если один и тот же параметр задан и в строке model, и в теле запроса (например, provider в строке model и provider.only в теле запроса), API вернёт ошибку 400. Неизвестный или повторяющийся параметр в строке model — тоже ошибка 400. Для сложного routing (order, ignore, country, несколько провайдеров в only) используйте обычный объект provider в теле запроса.

Список endpoint’ов модели

Чтобы узнать, какие провайдеры доступны для модели, их идентификаторы, цены и лимиты, используйте:

GET https://routerai.ru/api/v1/models/{author}/{model}/endpoints

Авторизация не требуется. Например, для модели anthropic/claude-sonnet-4.5 — GET /api/v1/models/anthropic/claude-sonnet-4.5/endpoints.

{
  "data": {
    "id": "anthropic/claude-sonnet-4.5",
    "name": "Anthropic: Claude Sonnet 4.5",
    "created": 1758809380,
    "description": "…",
    "architecture": {
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "tokenizer": "Claude"
    },
    "endpoints": [
      {
        "name": "Anthropic | anthropic/claude-sonnet-4.5",
        "provider_name": "Anthropic",
        "tag": "anthropic",
        "country": "us",
        "countries": ["us"],
        "context_length": 1000000,
        "quantization": "unknown",
        "max_completion_tokens": 64000,
        "supported_parameters": ["max_tokens", "temperature", "tools", "..."],
        "supported_apis": ["chat", "messages"],
        "status": 0,
        "pricing": {
          "prompt": 0.00030631848,
          "completion": 0.0015315924
        },
        "pricing_units": {
          "prompt": "token",
          "completion": "token"
        },
        "variable_pricings": [
          {
            "type": "prompt-threshold",
            "prompt": 0.00061263696,
            "threshold": 200000
          }
        ]
      }
    ]
  }
}

Поля endpoint’а:

Единицы цен. Один и тот же ключ pricing у разных моделей может означать разные единицы. Например, image_output у моделей генерации изображений — это цена за изображение (recraft/*, bytedance-seed/*), за мегапиксель результата (black-forest-labs/flux.2-*) или за выходной токен (openai/gpt-image-*, google/gemini-*-image). Всегда сверяйтесь с pricing_units, а не с названием ключа. У image-моделей в GET /api/v1/models есть также image_pricing — каталожные цены по вариантам (разрешение, качество), где pricing.image_output соответствует базовому варианту.

Endpoint’ы отсортированы в порядке приоритета маршрутизации: первым идёт провайдер, который будет выбран по умолчанию.

Примеры

Выбор страны обработки данных

Если вам критично, чтобы обработка данных происходила на территории России, укажите country:

curl -X POST "https://routerai.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "messages": [
      {"role": "user", "content": "Привет!"}
    ],
    "provider": {
      "country": "ru"
    }
  }'

Приоритетный порядок провайдеров

order указывает порядок предпочтения провайдеров: запрос уйдёт первому провайдеру из списка, который обслуживает модель. Если никого из списка нет, запрос уйдёт другому провайдеру модели — чтобы вместо этого получить ошибку, добавьте allow_fallbacks: false (см. строгий режим).

curl -X POST "https://routerai.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "Привет!"}],
    "provider": {
      "order": ["anthropic", "google"]
    }
  }'

Только указанные провайдеры (only)

only ограничивает выбор провайдера списком: провайдеры вне списка не используются. Если ни один провайдер из списка не обслуживает модель, вернётся ошибка 404 — allow_fallbacks на это не влияет. Чтобы задать порядок внутри списка, добавьте order.

curl -X POST "https://routerai.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Привет!"}],
    "provider": {
      "only": ["openai"]
    }
  }'

Исключение провайдеров (ignore)

ignore исключает провайдеров из выбора. Если исключены все провайдеры модели, вернётся ошибка 404.

curl -X POST "https://routerai.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "Привет!"}],
    "provider": {
      "ignore": ["google"]
    }
  }'

Строгий режим для order (allow_fallbacks: false)

По умолчанию order — это предпочтение: если ни одного провайдера из списка у модели нет, RouterAI обработает запрос другим провайдером. Установите allow_fallbacks: false, чтобы в этой ситуации получить ошибку 404. На only и ignore флаг не влияет — они и так жёсткие.

curl -X POST "https://routerai.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Привет!"}],
    "provider": {
      "order": ["openai", "azure"],
      "allow_fallbacks": false
    }
  }'

Комбинации

Поля можно комбинировать. Например, “не отправлять в Google и обрабатывать только в России”:

{
  "model": "openai/gpt-oss-120b",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "ignore": ["google"],
    "country": "ru"
  }
}

Или “предпочитать DeepSeek, потом Yandex, и только в России”:

{
  "model": "openai/gpt-4o",
  "messages": [{"role": "user", "content": "Привет!"}],
  "provider": {
    "order": ["deepseek", "yandex"],
    "country": "ru"
  }
}

Тарификация при выборе провайдера

Стоимость запроса считается по фактическому провайдеру, в которого ушёл запрос. Один и тот же запрос через разных провайдеров может стоить по-разному. Точная цена для каждого провайдера видна в личном кабинете, в детализации запросов и в списке endpoint’ов модели (GET /api/v1/models/{author}/{model}/endpoints).

При ошибках (когда запрос не выполнен) средства не списываются.

Возможные ошибки