Перейти к основному содержанию
POST
Ранжирование
Эндпоинт принимает запрос и набор документов, а возвращает документы, упорядоченные по релевантности запросу. Типичное применение — второй этап поиска: сначала вы отбираете кандидатов дешёвым способом, например векторным поиском по эмбеддингам, потом переранжируете их точной моделью. Работает с моделями из каталога GET /api/v1/models, у которых в capabilities есть значение "rerank".

Минимальный запрос

Сначала получите идентификатор модели из каталога, отфильтровав его по capabilities:
cURL
Идентификатор модели берите из GET /api/v1/models и подставляйте как есть. Состав моделей меняется, поэтому в рабочем коде не зашивайте его литералом. Если передать идентификатор обычной текстовой модели или неизвестное значение, придёт 404 с кодом model_not_found.

Поля запроса

В одном вызове можно смешивать документы-строки и документы-объекты. Документ-объект несёт либо text, либо image — визуальную модель, которая умеет читать изображения, можно попросить сравнить картинки с текстовым запросом.

Ответ

200 OK:
С top_n возвращаются только первые top_n позиций, но оценить модель может весь набор — порядок в results остаётся порядком убывания релевантности.

Стоимость

Списание зависит от фактической стоимости вызова. Поле usage.cost — сумма, списанная с вашего баланса; оно отсутствует, если списание не зафиксировано. Фактический остаток после вызова проверяйте через GET /api/v1/balance.

Проверки перед вызовом

Часть ошибок возвращается до обращения к модели: Ошибки приходят в конверте OpenAI — объект error с полями message, type, param и code. Полная таблица кодов — на странице Ошибки.

Что дальше

Каталог моделей

Фильтр по capabilities и цены моделей

Эмбеддинги

Векторный поиск как первый этап отбора

Баланс

Остаток кошелька по валютам

Ошибки

Полная таблица кодов

Авторизации

Authorization
string
header
обязательно

API-ключ в формате sk-.... Альтернативно — заголовок X-Api-Key: sk-... (совместимо с Anthropic SDK).

Тело

application/json
model
string
обязательно

Идентификатор модели из GET /api/v1/models: у неё в capabilities есть значение "rerank". Передаётся как есть.

query
string
обязательно

Запрос, относительно которого оценивается релевантность.

documents
any[]
обязательно

Документы: строки или объекты вида {"text": ...} / {"image": ...}. Пустой массив не принимается.

top_n
integer

Сколько лучших документов вернуть. По умолчанию возвращаются все.

user
string

Идентификатор пользователя на вашей стороне. Необязательно.

Maximum string length: 256

Ответ

Документы, упорядоченные по релевантности.

id
string
model
string

Идентификатор модели.

results
object[]

Документы, упорядоченные по убыванию релевантности.

usage
object