# Маршрутизация и кэш

У одной модели бывает несколько хостов: компаний, которые её обслуживают, каждая со своей ценой и условиями. Вызов идёт к первому подходящему хосту, а если тот не ответил по своей вине (5xx, таймаут, `429`), к следующему. Оплачивается вызов по цене хоста, который ответил, плюс наши 20%. Хосты модели, их цены и условия отдаёт `GET /v1/models` в `endpoints`, справочник хостов отдаёт `GET /v1/providers` (оба без ключа).

Внутри одной цены вызовы одного разговора идут к хосту, который ответил на прошлый вызов: у него уже лежит [кэш](#кэш-промпта). Выбор держится час без вызовов.

## Выбор хостов: provider

Объект `provider` в теле запроса выбирает хосты так же, как у OpenRouter. Хосту он не передаётся.

| Ключ | Описание |
| --- | --- |
| `only` | Хосты, к которым можно отправить вызов, по имени (`endpoints` модели в `GET /v1/models`); остальные исключаются. |
| `ignore` | Хосты, к которым вызов не отправляется. |
| `order` | Хосты, которые пробуются первыми, в этом порядке; остальные идут следом, если `allow_fallbacks` не `false`. |
| `allow_fallbacks` | `false` оставляет вызов только на хостах из `order`. По умолчанию `true`. |
| `sort` | `price` ставит первым самый дешёвый хост. `throughput` и `latency` отказывают с `unsupported_provider_preference`: скорость хостов пока не измеряется. Форма объекта `{"by": "price", "partition": "model"}` читается так же. |
| `max_price` | Потолок цены хоста в долларах США за 1M токенов: `prompt` и `completion`. Хост дороже потолка исключается; если не осталось ни одного, ответ `price_above_max`. `request` и `image` принимаются и не применяются: платы за запрос и за картинку у вызова здесь нет. |
| `require_parameters` | Здесь всегда `true`, что бы ни пришло: хост, который не принимает поле запроса (`tools`), не выбирается. |
| `data_collection` | `deny` исключает хосты, которые могут обучаться на данных или не объявили условия. По умолчанию `allow`. |
| `zdr` | `true` оставляет вызов на хостах с подписанным условием нулевого хранения. |
| `data_region` | Оставляет вызов на хостах, которые обрабатывают текст в этом регионе (`ru`). Модель без такого хоста получает отказ, вызов не уходит за рубеж запасным путём. |

`max_price` задаётся в долларах США за 1M токенов, как у OpenRouter: код, написанный под OpenRouter, работает без правок. С ним сравнивается цена, которую платите вы, то есть цена хоста уже с нашими 20%. Списание с баланса идёт в рублях по этой цене, пересчитанной по официальному курсу ЦБ РФ на день вызова. Ключ `provider`, которого нет в таблице, отклоняется, а не пропускается: обещание о данных, которое мы не держим, хуже отказа.

| HTTP | type | Код | message | Повтор |
| --- | --- | --- | --- | --- |
| 400 | `invalid_request_error` | `invalid_provider_preferences` | provider must be an object of OpenRouter's provider preferences. | нет |
| 400 | `invalid_request_error` | `unsupported_provider_preference` | The provider object has a preference this API does not honour. | нет |
| 400 | `invalid_request_error` | `unknown_provider` | The provider object names a host this API does not route to. | нет |
| 400 | `invalid_request_error` | `price_above_max` | Every eligible host of the model is priced above provider.max_price. | нет |
| 404 | `not_found_error` | `no_eligible_host` | No host of the model meets the request's provider preferences. | нет |

Ответ на `no_eligible_host` и `price_above_max` называет, почему исключён каждый хост.

## Запасные модели: models

`models: [...]` задаёт цепочку моделей, как у OpenRouter. Если у первой модели не ответил ни один хост по своей вине или промпт не поместился в её окно, вызов переходит к следующей. Поле `model`, если оно есть, идёт в цепочке первым. Ответ называет модель, которая ответила, и оплачивается по её хосту. Число моделей в цепочке ограничено; лишние и не-строки отклоняются с кодом `invalid_models`.

```json
{
  "model": "<вендор>/<модель>",
  "models": ["<вендор>/<запасная-модель>"],
  "messages": [{"role": "user", "content": "…"}]
}
```

## Выбор модели auto

`model: "auto"` выбирает модель сам: самую дешёвую для этого вызова среди тех, у которых остался хост после ваших фильтров `provider` (условия данных и `max_price` тоже), есть инструменты, если они в запросе, и окно вмещает промпт и запрошенный ответ. Выбор закрепляется за разговором на час без вызовов, чтобы кэш не терялся; модель меняется, только если перестала подходить (промпт перерос её окно). Ответ называет модель, которая ответила.

Плагин `auto-router` сужает выбор списком `allowed_models`, как у OpenRouter: `"plugins": [{"id": "auto-router", "allowed_models": ["<вендор>/*"]}]` (допускается `*` в шаблоне).

Если подходящей модели нет, вызов отклоняется с кодом `no_auto_model`.

## Данные в РФ

Часть моделей обслуживают хосты, которые обрабатывают текст запроса на своих серверах в РФ (например, Yandex AI Studio и GigaChat). На странице [«Модели»](/models) у такой модели стоит пометка «Данные в РФ», и оттуда же ведёт ссылка на раздел с ценами только хостов в РФ, пока в каталоге есть хотя бы одна такая модель. На странице каждой модели у хоста указано, обрабатывает ли он данные в РФ. Страница называет только регион обработки у хоста и не заменяет вашу оценку соответствия 152-ФЗ.

- `GET /v1/models?data_region=ru` отдаёт только модели, у которых есть хост в РФ, и в `endpoints` только эти хосты.
- В запросе `"provider": {"data_region": "ru"}` вызов уходит только к хостам в РФ. Если у модели такого хоста нет или ни один из них не ответил, вызов отклоняется: к хосту за рубежом он не переходит. Цепочка `models` и `auto` читают тот же фильтр для каждой модели.
- Вызов оплачивается по цене хоста в РФ, который ответил, плюс наши 20%, как и любой другой вызов.

```json
{
  "model": "<вендор>/<модель>",
  "messages": [{"role": "user", "content": "…"}],
  "provider": {"data_region": "ru"}
}
```

## Хранение и обучение

`"provider": {"zdr": true}` оставляет вызов на хостах с подписанным условием нулевого хранения, `"data_collection": "deny"` исключает хосты, которые могут обучаться на данных или не объявили условия. Условия каждого хоста и ссылки на его политику конфиденциальности и условия отдаёт `GET /v1/providers`. Сами мы не храним ни промпт, ни ответ: журнал вызова держит модель, хост, токены, стоимость и то, чем вызов кончился.

## Кэш промпта

Повторяющаяся часть (system, описания инструментов, ранние сообщения разговора) должна идти первой и не меняться между вызовами, тогда следующий вызов читает её из кэша дешевле. Как хост держит кэш, называет `endpoints[].cache`: хосты `auto_prefix` сами кэшируют самое длинное повторяющееся начало промпта, передавать ничего не нужно.

Чтобы вызовы одного разговора попадали в один кэш, назовите разговор. Ключ читается в таком порядке: заголовок `x-claude-code-session-id` (его шлёт Claude Code), `session_id`, `prompt_cache_key`, `metadata.user_id` на проводе Anthropic, `user`. Ключ остаётся внутри вашей организации: хост получает ключ, смешанный с организацией, а не тот, что прислали вы. Без ключа разговор определяется по system и первому сообщению.

На `/v1/messages` метки `cache_control` сохраняются: хост, который сам говорит на Anthropic Messages (`messages` в `endpoints[].wires`), получает их в теле; хосту Chat Completions, который кэширует по меткам (`explicit_breakpoints`), метки переносятся на части сообщений; у остальных хостов меткам не к чему привязаться, и хост кэширует сам. Из самой метки доходит только `type`:

| Ключ | Что с ним происходит |
| --- | --- |
| `type` | проходит к хосту как прислано |
| `ttl` | принимается и отбрасывается |
| `scope` | принимается и отбрасывается |

`ttl` и `scope` убираются, потому что меняют цену, которую резерв вызова не учитывает: метка остаётся и живёт срок хоста по умолчанию (у Anthropic пять минут). Часового кэша через этот API нет. Кэш и так разделён по организации, поэтому `scope` не нужен.

Claude Code ставит первой строкой system строку `x-anthropic-billing-header: …`, значение которой меняется в каждом запросе. Она ломает любой кэш префикса, поэтому мы убираем её, прежде чем промпт уйдёт хосту.

Ответ называет, сколько прочитано из кэша и записано в него:

| Провод | Прочитано | Записано |
| --- | --- | --- |
| OpenAI | `usage.prompt_tokens_details.cached_tokens` | `usage.prompt_tokens_details.cache_write_tokens` |
| Anthropic | `usage.cache_read_input_tokens` | `usage.cache_creation_input_tokens` (по уровням в `usage.cache_creation`) |

Чтение из кэша оплачивается по цене `input_cache_read`, запись по цене `input_cache_write` того хоста, который ответил. Экономию на кэше в рублях называет `cache_discount` в [`GET /v1/generation`](/docs/model-api-requests#учёт-и-стоимость).

## Плагины

`plugins` принимает плагины OpenRouter, которые есть в таблице; остальные отклоняются с кодом `unsupported_plugin`.

| id плагина | Что с ним происходит |
| --- | --- |
| `auto-router` | заменяется: его читает API, хост получает значение API |
| `context-compression` | принимается и отбрасывается |
