Маршрутизация и кэш
У одной модели бывает несколько хостов: компаний, которые её обслуживают, каждая со своей ценой и условиями. Вызов идёт к первому подходящему хосту, а если тот не ответил по своей вине (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.
Выбор модели auto
model: "auto" выбирает модель сам: самую дешёвую для этого вызова среди тех, у которых остался хост после ваших фильтров provider (условия данных и max_price тоже), есть инструменты, если они в запросе, и окно вмещает промпт и запрошенный ответ. Выбор закрепляется за разговором на час без вызовов, чтобы кэш не терялся; модель меняется, только если перестала подходить (промпт перерос её окно). Ответ называет модель, которая ответила.
Плагин auto-router сужает выбор списком allowed_models, как у OpenRouter: "plugins": [{"id": "auto-router", "allowed_models": ["<вендор>/*"]}] (допускается * в шаблоне).
Если подходящей модели нет, вызов отклоняется с кодом no_auto_model.
Данные в РФ
Часть моделей обслуживают хосты, которые обрабатывают текст запроса на своих серверах в РФ (например, Yandex AI Studio и GigaChat). На странице «Модели» у такой модели стоит пометка «Данные в РФ», и оттуда же ведёт ссылка на раздел с ценами только хостов в РФ, пока в каталоге есть хотя бы одна такая модель. На странице каждой модели у хоста указано, обрабатывает ли он данные в РФ. Страница называет только регион обработки у хоста и не заменяет вашу оценку соответствия 152-ФЗ.
GET /v1/models?data_region=ruотдаёт только модели, у которых есть хост в РФ, и вendpointsтолько эти хосты.- В запросе
"provider": {"data_region": "ru"}вызов уходит только к хостам в РФ. Если у модели такого хоста нет или ни один из них не ответил, вызов отклоняется: к хосту за рубежом он не переходит. Цепочкаmodelsиautoчитают тот же фильтр для каждой модели. - Вызов оплачивается по цене хоста в РФ, который ответил, плюс наши 20%, как и любой другой вызов.
Хранение и обучение
"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.
Плагины
plugins принимает плагины OpenRouter, которые есть в таблице; остальные отклоняются с кодом unsupported_plugin.
| id плагина | Что с ним происходит |
|---|---|
auto-router | заменяется: его читает API, хост получает значение API |
context-compression | принимается и отбрасывается |
Частые вопросы
В какой валюте provider.max_price?
В долларах США за 1M токенов, как у OpenRouter, чтобы код, написанный под OpenRouter, работал без правок. Сравнивается цена, которую платите вы, то есть уже с нашими 20%. Списание с баланса идёт в рублях по цене хоста, который ответил, плюс наши 20%: цена в долларах пересчитывается по официальному курсу ЦБ РФ на день вызова.
Как оставить обработку данных в РФ?
Передайте "provider": {"data_region": "ru"}. Вызов уйдёт только к хостам, которые обрабатывают текст в РФ; если таких нет или ни один не ответил, вызов отклоняется, к хосту за рубежом он не переходит.
Работает ли cache_control с ttl "1h"?
Метка cache_control сохраняется, а ключи ttl и scope из неё убираются: кэш живёт срок хоста по умолчанию. Часовой кэш стоит у хоста дороже, а резерв вызова его не учитывает.