Передайте поисковый запрос и найденные текстовые фрагменты. Модель оценит их релевантность и вернёт результаты в порядке убывания оценки. Реранжирование выполняется после поиска и до передачи контекста чат-модели.

Совместимый путь: /rerank. Требуется API-ключ с gateway:write, разрешённая модель и положительный баланс организации. Лимиты ключа на запросы и расходы также применяются.

Первый запрос

curl --fail-with-body "https://api.kodikrouter.ru/v1/rerank" \
  -H "Authorization: Bearer $KODIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/rerank-4-pro",
    "query": "What is the capital of France?",
    "documents": ["Berlin is the capital of Germany.", "Paris is the capital of France."],
    "top_n": 1
  }'

Задайте переменную KODIK_API_KEY своим ключом перед запуском. ID модели берите из актуального каталога.

Ответ

{
  "id": "gen-rerank-example",
  "model": "cohere/rerank-4-pro",
  "results": [{"index": 1, "relevance_score": 0.95}],
  "usage": {"search_units": 1, "cost": 0.0025},
  "provider": "Cohere"
}

Иллюстративный пример: оценки и стоимость зависят от модели и запроса. index — позиция документа во входном массиве, relevance_score — оценка от 0 до 1. Результаты отсортированы по убыванию оценки. При return_documents: true поле document.text содержит исходный текст.

Стоимость и каталог

curl -sS "https://api.kodikrouter.ru/v1/catalog/models?api_surfaces=rerank"

Реранкеры имеют api_surface: rerank и pricing_basis: provider_reported. Нулевые значения цен за входные и выходные токены не означают бесплатную модель. Токенный калькулятор для таких запросов не применяется.

usage.cost — фактическая стоимость провайдера в USD. Списание в RUB учитывает курс и наценку шлюза. В зависимости от модели usage содержит search_units или total_tokens. Для оплаты требуется положительный баланс, даже если отдельный upstream-вариант вернёт нулевой cost.

Ограничения и конфиденциальность

До 1 000 документов и 1 000 000 символов суммарно в query и documents. Дополнительно действует ограничение размера HTTP-тела: по умолчанию 2 000 000 байт. Лимиты контекста и доступность зависят от провайдера. Поддерживается только текст; изображения, stream и параметры chat/completions не принимаются.

Повторные запросы и ошибки

Необязательный заголовок Idempotency-Key сохраняет успешный ответ на 24 часа для той же организации и API-ключа, включая оба пути. Повтор с тем же телом возвращает сохранённый ответ без нового вызова и списания. Одновременный запрос или другое тело с тем же ключом возвращают 409. Для нового запроса используйте новый ключ. При сбое процесса между списанием и сохранением ответа строго однократное выполнение не гарантируется.

401 — ключ отсутствует или недействителен; 403 — недостаточно прав или модель запрещена; 402 — недостаточно средств; 429 — лимит запросов; 413 — превышен размер тела. Неверный формат или использование чат-модели — 400. Некорректные оценки или отсутствие данных о стоимости — 502; таймаут — 504. Upstream 400/402/404/409/429 сохраняют статус. Неуспешные и невалидные ответы не списываются локально, но провайдер может учесть выполненный вызов.