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

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

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

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

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

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

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

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

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

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

Примечание про область применения order/only/ignore. Эти поля — предпочтения маршрутизации, а не жёсткое ограничение: они определяют, какого провайдера RouterAI выберет для обработки запроса, но в отдельных случаях — например, при резервной попытке после сбоя провайдера — запрос может быть обработан провайдером вне списка. Если под указанные предпочтения не подходит ни один доступный провайдер, при allow_fallbacks: true (по умолчанию) запрос уйдёт провайдеру по умолчанию, а при allow_fallbacks: false вернётся ошибка 404. Жёсткое ограничение даёт 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

Как и в body-контракте, provider сам по себе — предпочтение, а не жёсткое ограничение: при недоступности (или опечатке в слаге) запрос уйдёт провайдеру по умолчанию. Если нужен жёсткий пиннинг на конкретного провайдера, всегда указывайте пару provider=<slug>&allow_fallbacks=false — тогда несоответствие даст ошибку 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}/{slug}/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",
        "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
        },
        "variable_pricings": [
          {
            "type": "prompt-threshold",
            "prompt": 0.00061263696,
            "threshold": 200000
          }
        ]
      }
    ]
  }
}

Поля endpoint’а:

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 указывает порядок предпочтения провайдеров: запрос уйдёт первому доступному провайдеру из списка.

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 ограничивает выбор провайдера списком. Если ни один провайдер из списка недоступен, запрос по умолчанию уйдёт провайдеру вне списка — чтобы вместо этого получить ошибку, добавьте 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": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Привет!"}],
    "provider": {
      "only": ["openai"]
    }
  }'

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

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"]
    }
  }'

Строгий режим предпочтений (allow_fallbacks: false)

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

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"],
      "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}/{slug}/endpoints).

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

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