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

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

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

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

> Когда вы отправляете запрос с параметрами `tools` или `tool_choice`, RouterAI будет маршрутизировать его только к тем провайдерам, которые поддерживают использование инструментов. Аналогично, если вы установите `max_tokens`, RouterAI будет маршрутизировать запрос только к провайдерам, поддерживающим ответ такой длины.

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

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

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

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

| Поле | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `order` | `Array<String>` | — | Приоритетный список slug'ов провайдеров — подсказка маршрутизации, применяется когда запрос проходит через нашу мульти-провайдерную сеть. |
| `only` | `Array<String>` | — | Whitelist провайдеров для мульти-провайдерной маршрутизации. |
| `ignore` | `Array<String>` | — | Blacklist провайдеров для мульти-провайдерной маршрутизации. |
| `allow_fallbacks` | `Boolean` | `true` | При `false` RouterAI не пытается использовать резервный провайдер, если выбранный провайдер вернул ошибку — клиент получит эту ошибку как есть. |
| `country` | `String` | — | Двухбуквенный код страны для фильтрации провайдеров по гео-политике (например, `"ru"`). |

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

> **Примечание про область применения `order/only/ignore`.** Если для запрошенной модели у нас настроен прямой провайдер или специальный маршрут, мы используем его — поля `order/only/ignore` в этом случае на наш выбор не влияют. Они применяются, когда запрос идёт через гибкую мульти-провайдерную маршрутизацию. Для гарантированного ограничения по гео-политике используйте `country`, для отключения резервных попыток — `allow_fallbacks: false`.

## Список 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`.

```json
{
  "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'а:

| Поле | Описание |
| --- | --- |
| `tag` | Слаг провайдера — именно это значение передаётся в `provider.order`, `provider.only`, `provider.ignore`. |
| `provider_name`, `name` | Человекочитаемые названия провайдера и endpoint'а. |
| `country` | Двухбуквенный код страны провайдера — для фильтра `provider.country`. |
| `context_length` | Размер контекста (в токенах) у этого провайдера. |
| `max_completion_tokens`, `max_prompt_tokens` | Лимиты выходных/входных токенов (`max_prompt_tokens` присутствует, только если известен). |
| `quantization` | Квантизация модели у провайдера (`fp8`, `bf16`, `unknown`, …). Присутствует не у всех endpoint'ов. |
| `supported_parameters` | Параметры запроса, которые поддерживает этот endpoint. |
| `supported_apis` | Протоколы API, доступные через этот endpoint (`chat`, `messages`, `responses`, `embeddings`, …). |
| `status` | `0` — работает штатно; отрицательное значение — endpoint временно деприоритизирован. |
| `pricing` | Цены **в рублях за токен** (или за единицу — запрос, изображение, секунда) конкретно у этого провайдера. Та же схема расчёта, что в `GET /api/v1/models`. |
| `variable_pricings` | Тарифные пороги: цены после превышения `threshold` токенов промпта. |

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

## Примеры

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

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

```bash
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` указывает порядок предпочтения провайдеров. Применяется при маршрутизации через нашу мульти-провайдерную сеть.

```bash
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`)

Применяется при маршрутизации через мульти-провайдерную сеть:

```bash
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`)

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

### Отключение fallback (`allow_fallbacks: false`)

По умолчанию, если выбранный провайдер вернул ошибку, RouterAI повторяет запрос через резервный провайдер. Если это поведение нежелательно — например, вы хотите гарантированно получить ответ только от выбранного провайдера, либо предпочитаете увидеть его исходную ошибку:

```bash
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": {
      "allow_fallbacks": false
    }
  }'
```

### Комбинации

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

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

Или "при мульти-провайдерной маршрутизации предпочитать DeepSeek, потом Yandex, и только в России":

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

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

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

При ошибках (когда запрос не выполнен), а также при `allow_fallbacks: false`, если выбранный провайдер вернул ошибку, средства не списываются.

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

| Код | Когда возникает |
| --- | --- |
| `503` | Для запрошенной модели нет ни одного доступного провайдера. |
| `402` | Недостаточно средств на балансе. |
| `500` / `502` / `503` | Ошибка провайдера. Если `allow_fallbacks: true` (default) — RouterAI попробовал резервный провайдер и тот тоже не отработал. При `allow_fallbacks: false` — клиент получает исходную ошибку выбранного провайдера, без повторных попыток. |