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

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

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

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

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

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

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

HTTPtypeКодmessageПовтор
400invalid_request_errorinvalid_provider_preferencesprovider must be an object of OpenRouter's provider preferences.нет
400invalid_request_errorunsupported_provider_preferenceThe provider object has a preference this API does not honour.нет
400invalid_request_errorunknown_providerThe provider object names a host this API does not route to.нет
400invalid_request_errorprice_above_maxEvery eligible host of the model is priced above provider.max_price.нет
404not_found_errorno_eligible_hostNo 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). На странице «Модели» у такой модели стоит пометка «Данные в РФ», и оттуда же ведёт ссылка на раздел с ценами только хостов в РФ, пока в каталоге есть хотя бы одна такая модель. На странице каждой модели у хоста указано, обрабатывает ли он данные в РФ. Страница называет только регион обработки у хоста и не заменяет вашу оценку соответствия 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: …, значение которой меняется в каждом запросе. Она ломает любой кэш префикса, поэтому мы убираем её, прежде чем промпт уйдёт хосту.

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

ПроводПрочитаноЗаписано
OpenAIusage.prompt_tokens_details.cached_tokensusage.prompt_tokens_details.cache_write_tokens
Anthropicusage.cache_read_input_tokensusage.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 из неё убираются: кэш живёт срок хоста по умолчанию. Часовой кэш стоит у хоста дороже, а резерв вызова его не учитывает.

Была ли страница полезна?