Реранкер получает запрос и список документов и возвращает их в порядке, в каком они отвечают на запрос: лучшие первыми, у каждого оценка relevance_score. Обычно его ставят после поиска: векторный или полнотекстовый поиск находит 50–100 кандидатов, реранкер выбирает из них несколько самых подходящих, и только они уходят в модель. Так ответ точнее, а запрос к модели короче.

Стрима нет: один POST → один JSON-ответ. Список реранкеров — в каталоге или запросом GET /v1/models?output_modalities=rerank.

Эндпоинт

POSThttps://api.hubris.pw/v1/rerank

Заголовки:

Header	Значение
`Authorization`	`Bearer sk-gw-...` (обязательно)
`Content-Type`	`application/json` (обязательно)

Тело запроса

Поле	Тип	По умолчанию	Описание
`model`	`string`	—	ID реранкера, например `cohere/rerank-v3.5`.
`query`	`string`	—	Запрос, по которому сортируются документы.
`documents`	`array`	—	От 1 до 1000 документов: строки или объекты `{ "text": "…" }`. Мультимодальные реранкеры принимают и `{ "image": "<URL или data URI>" }`.
`top_n`	`integer` > 0	все	Сколько самых подходящих документов вернуть.
`user`	`string`	—	Идентификатор конечного пользователя для трекинга абьюза на стороне провайдера.

Минимальный пример

В OpenAI SDK метода для реранкинга нет — это обычный HTTP-запрос.

curl -s https://api.hubris.pw/v1/rerank \
-H "Authorization: Bearer sk-gw-..." \
-H "Content-Type: application/json" \
-d '{
  "model": "cohere/rerank-v3.5",
  "query": "Как вернуть деньги за заказ?",
  "documents": [
    "Возврат оформляется в личном кабинете в разделе «Заказы».",
    "Доставка по Москве занимает один день.",
    "Деньги приходят на карту в течение 10 дней после возврата."
  ],
  "top_n": 2
}'

curl -s https://api.hubris.pw/v1/rerank \-H "Authorization: Bearer sk-gw-..." \-H "Content-Type: application/json" \-d '{  "model": "cohere/rerank-v3.5",  "query": "Как вернуть деньги за заказ?",  "documents": [    "Возврат оформляется в личном кабинете в разделе «Заказы».",    "Доставка по Москве занимает один день.",    "Деньги приходят на карту в течение 10 дней после возврата."  ],  "top_n": 2}'

import requests

res = requests.post(
  "https://api.hubris.pw/v1/rerank",
  headers={"Authorization": "Bearer sk-gw-..."},
  json={
      "model": "cohere/rerank-v3.5",
      "query": "Как вернуть деньги за заказ?",
      "documents": [
          "Возврат оформляется в личном кабинете в разделе «Заказы».",
          "Доставка по Москве занимает один день.",
          "Деньги приходят на карту в течение 10 дней после возврата.",
      ],
      "top_n": 2,
  },
)
for r in res.json()["results"]:
  print(r["index"], round(r["relevance_score"], 3))

import requestsres = requests.post(  "https://api.hubris.pw/v1/rerank",  headers={"Authorization": "Bearer sk-gw-..."},  json={      "model": "cohere/rerank-v3.5",      "query": "Как вернуть деньги за заказ?",      "documents": [          "Возврат оформляется в личном кабинете в разделе «Заказы».",          "Доставка по Москве занимает один день.",          "Деньги приходят на карту в течение 10 дней после возврата.",      ],      "top_n": 2,  },)for r in res.json()["results"]:  print(r["index"], round(r["relevance_score"], 3))

const res = await fetch("https://api.hubris.pw/v1/rerank", {
method: "POST",
headers: {
  Authorization: `Bearer ${process.env.HUBRIS_API_KEY}`,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  model: "cohere/rerank-v3.5",
  query: "Как вернуть деньги за заказ?",
  documents: [
    "Возврат оформляется в личном кабинете в разделе «Заказы».",
    "Доставка по Москве занимает один день.",
    "Деньги приходят на карту в течение 10 дней после возврата.",
  ],
  top_n: 2,
}),
});
const { results } = await res.json();
console.log(results.map((r) => r.index)); // [0, 2]

const res = await fetch("https://api.hubris.pw/v1/rerank", {method: "POST",headers: {  Authorization: `Bearer ${process.env.HUBRIS_API_KEY}`,  "Content-Type": "application/json",},body: JSON.stringify({  model: "cohere/rerank-v3.5",  query: "Как вернуть деньги за заказ?",  documents: [    "Возврат оформляется в личном кабинете в разделе «Заказы».",    "Доставка по Москве занимает один день.",    "Деньги приходят на карту в течение 10 дней после возврата.",  ],  top_n: 2,}),});const { results } = await res.json();console.log(results.map((r) => r.index)); // [0, 2]

Ответ

Ответ на пример выше (запрос 13.10.2026):

{
  "id": "gen-rerank-1791920607-d5ZkoUBZ7glBVswTgA2R",
  "model": "cohere/rerank-v3.5",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.56690645,
      "document": { "text": "Возврат оформляется в личном кабинете в разделе «Заказы»." }
    },
    {
      "index": 2,
      "relevance_score": 0.2046759,
      "document": { "text": "Деньги приходят на карту в течение 10 дней после возврата." }
    }
  ],
  "usage": {
    "search_units": 1,
    "cost": 13
  }
}

Поля ответа

Поле	Тип	Описание
`model`	`string`	Модель, которая обработала запрос.
`results[]`	`array`	Документы по убыванию близости к запросу, не больше `top_n`.
`results[].index`	`integer`	Номер документа во входном `documents` (с нуля).
`results[].relevance_score`	`number`	Оценка близости: чем больше, тем лучше. Шкала у моделей разная — сравнивайте оценки только внутри одного ответа.
`results[].document`	`object`	Сам документ, как он пришёл в запросе.
`usage.search_units`	`integer`	Поисковые единицы — у моделей с оплатой за поиск.
`usage.total_tokens`	`integer`	Токены входа — у моделей с оплатой за токены.
`usage.cost`	`integer`	Стоимость в копейках. Расширение Hubris.

HTTP-коды

Код	Когда
`200`	Успешный ответ.
`400`	Тело запроса не соответствует схеме (нет `query`, пустой `documents`, больше 1000 документов).
`401`	Ключ отсутствует, отозван или невалиден.
`402`	Недостаточно средств на балансе.
`404`	Модели нет в каталоге, она снята или это не реранкер — что именно, сказано в сообщении.
`429`	Превышен лимит расхода ключа или дневной лимит бесплатных моделей.
`502 / 503 / 504`	Сбой у провайдера, курса ЦБ или таймаут. Списания нет.

Формат тела ошибки и стратегия повторов — Ошибки.

Биллинг

Единица оплаты зависит от модели и указана на её карточке в каталоге:

за поиск — модели Cohere. Один поиск — запрос, в котором до 100 документов; 150 документов — уже два поиска;
за токены входа — остальные реранкеры: считаются запрос и все документы.

Списание — после успешного ответа, по фактической стоимости запроса; сумма попадает в usage.cost и в журнал запросов. За отклонённые запросы и сбои провайдера не списывается ничего. Бесплатные реранкеры работают и при нулевом балансе, в пределах дневного лимита.

Что дальше

POST /v1/embeddings — векторы для первого этапа поиска.
Модели — как выбрать модель.
Ошибки — что делать на 429 и 502.

Обновлено: 13 октября 2026 г.

POST /v1/rerank