Message Transforms (Трансформация сообщений)

Message Transforms — плагины, которые преобразуют промпт перед отправкой провайдеру. Сейчас доступен один плагин — контекстная компрессия (context-compression): он помогает, когда промпт не помещается в контекстное окно модели или когда сообщений слишком много.

Плагины передаются в теле запроса top-level полем plugins:

{
  "plugins": [{ "id": "context-compression" }],
  "model": "anthropic/claude-sonnet-4.5",
  "messages": []
}

Поле plugins передаётся провайдеру как есть. Ниже — единственный плагин, который сейчас поддерживается.

Контекстная компрессия (context-compression)

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

Плагин применим не только к объёму, но и к количеству сообщений. Например, у моделей Anthropic максимум 1000 сообщений: при превышении лимита с включённой компрессией остаётся половина сообщений сначала и половина с конца диалога.

curl https://api.ru-openrouter.ru/v1/chat/completions \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "plugins": [{ "id": "context-compression" }],
    "messages": [
      {"role": "user", "content": "Очень длинный промпт..."}
    ]
  }'

import requests

response = requests.post(
    "https://api.ru-openrouter.ru/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk_ваш_api_ключ",
        "Content-Type": "application/json",
    },
    json={
        "model": "anthropic/claude-sonnet-4.5",
        "plugins": [{"id": "context-compression"}],
        "messages": [
            {"role": "user", "content": "Очень длинный промпт..."}
        ],
    },
)

Как выбирается модель

Когда компрессия включена, сначала подбирается модель, контекст которой не меньше половины требуемого объёма (входные + выходные токены). Например, если промпту нужно 10 000 токенов, подойдут модели с контекстом от 5 000. Если таких моделей нет, используется модель с максимально доступным контекстом.

Если компрессия выключена, а объём запроса превышает контекст модели, запрос завершается ошибкой с предложением сократить промпт или включить контекстную компрессию.

Включение и отключение

1. Через тело запроса (per-request)

Добавьте плагин в поле plugins. Это самый явный способ — он имеет приоритет над настройками личного кабинета:

{
  "plugins": [{ "id": "context-compression" }],
  "messages": []
}

Отключить компрессию для конкретного запроса (в том числе там, где она включена по умолчанию) можно так:

{
  "plugins": [{ "id": "context-compression", "enabled": false }],
  "messages": []
}

2. Через заголовок запроса (per-request)

Добавьте заголовок X-OpenRouter-Context-Compression: true, чтобы включить компрессию для конкретного запроса, или false, чтобы не добавлять плагин. Заголовок обрабатывается на стороне API и провайдеру не передаётся.

curl https://api.ru-openrouter.ru/v1/chat/completions \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -H "X-OpenRouter-Context-Compression: true" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "Очень длинный промпт..."}]
  }'

3. Через личный кабинет (настройка пользователя)

В личном кабинете (Dashboard) доступен переключатель «Промпт компрессор». При включении плагин context-compression автоматически добавляется ко всем запросам /v1/chat/completions данного пользователя — указывать его в каждом запросе не нужно.

Приоритет

1. Если в теле запроса уже есть плагин context-compression — он используется как есть, настройка из личного кабинета и заголовок не применяются.
2. Иначе X-OpenRouter-Context-Compression переопределяет настройку личного кабинета.
3. Если ни плагина в теле, ни заголовка нет — используется настройка «Промпт компрессор» из личного кабинета.
4. Если настройка выключена и заголовок не задан — плагин не добавляется.

Модели с контекстом 8k и меньше: для всех эндпоинтов с контекстом ≤ 8 192 токена компрессия включена по умолчанию. Если тумблер выключен, API не добавляет плагин, но такие модели всё равно будут сжимать промпт на стороне провайдера. Чтобы отключить компрессию принудительно, передайте plugins: [{"id": "context-compression", "enabled": false}] в теле запроса.

Поддерживаемые эндпоинты

Плагин context-compression применяется только к эндпоинту Chat Completions — и по настройке из личного кабинета, и по заголовку.

Контекстная компрессия автоматически пропускается для моделей, которые генерируют только изображения (без текста): это сохраняет входные изображения в image-to-image запросах. Мультимодальные модели, которые возвращают и текст, и изображения (например, Gemini), компрессию используют.

Тарификация

Компрессия уменьшает объём входных токенов, поэтому снижает стоимость запроса: тарифицируется то, что фактически обработала модель. Отдельной платы за использование плагина нет — счёт формируется по usage ответа провайдера, как у обычного запроса.