# Сервис-тиры (Service Tiers)

Сервис-тиры позволяют выбрать баланс между **ценой** и **скоростью** обработки запроса. Параметр `service_tier` принимает два значения:

- **`flex`** — сниженная цена (обычно около −50%) в обмен на повышенную задержку и меньшую доступность мощностей.
- **`priority`** — ускоренная обработка за повышенную стоимость.

Если параметр не указан, запрос обрабатывается стандартным тиром по обычной цене.

## Как запросить тир

Передайте `service_tier` верхним полем в теле запроса:

```bash
curl https://routerai.ru/api/v1/chat/completions \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5",
    "messages": [{ "role": "user", "content": "Привет!" }],
    "service_tier": "priority"
  }'
```

Параметр работает во всех совместимых форматах API: Chat Completions, Responses и Messages (Anthropic-совместимый).

## Поддерживаемые провайдеры

Сервис-тиры доступны для отдельных моделей у провайдеров, которые их поддерживают:

| Провайдер | `flex` | `priority` |
| --- | :---: | :---: |
| OpenAI | ✅ | ✅ |
| Google Vertex AI | ✅ | ✅ |
| Google AI Studio | ✅ | ✅ |
| xAI | — | ✅ |

Если запрошенный тир недоступен для выбранной модели/провайдера, запрос обслуживается стандартным тиром.


## Поведение маршрутизации

RouterAI маршрутизирует тир-запросы по-разному:

- **`priority`** — при невозможности выполнить запрос с приоритетным тиром он будет выполнен со стандартным тиром. Тарификация всегда идёт по фактически использованному тиру.
- **`flex`** — маршрутизация ограничивается только flex-совместимыми провайдерами. Если ни один недоступен, вернётся ошибка.

## Тир-суффиксы в идентификаторах провайдера

В дополнение к полю `service_tier` тир можно указать прямо в идентификаторе провайдера внутри `provider.order` или `provider.only`, добавив суффикс `/flex` или `/priority`:

```json
{
  "model": "openai/gpt-5",
  "messages": [{ "role": "user", "content": "Привет!" }],
  "provider": {
    "order": ["openai/priority"]
  }
}
```


## Тир в ответе

Фактический тир, которым была обслужена генерация, возвращается в ответе в поле `service_tier`. Расположение зависит от формата API:

- **Chat Completions** и **Responses** — верхнеуровневое поле ответа.
- **Messages** (Anthropic-совместимый) — внутри объекта `usage`.

Возможные значения: `default`, `flex`, `priority` либо `null`, если апстрим не сообщает тир.

```json
{
  "id": "rai-...",
  "model": "openai/gpt-5",
  "service_tier": "flex",
  "choices": [ ... ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 34, "total_tokens": 46 }
}
```