> ## Documentation Index > Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Ранжирование > POST /api/v1/rerank — оценка релевантности документов относительно запроса Эндпоинт принимает запрос и набор документов, а возвращает документы, упорядоченные по релевантности запросу. Типичное применение — второй этап поиска: сначала вы отбираете кандидатов дешёвым способом, например векторным поиском по эмбеддингам, потом переранжируете их точной моделью. Работает с моделями из каталога `GET /api/v1/models`, у которых в `capabilities` есть значение `"rerank"`. ## Минимальный запрос Сначала получите идентификатор модели из каталога, отфильтровав его по `capabilities`: ```bash cURL theme={null} theme={null} MODEL=$(curl -s https://speshu.ai/api/v1/models \ | jq -r '.data[] | select(.capabilities | index("rerank")) | .id' \ | head -n 1) curl https://speshu.ai/api/v1/rerank \ -H "Authorization: Bearer $SPESHU_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"model\": \"$MODEL\", \"query\": \"Как вернуть товар?\", \"documents\": [ \"Возврат товара возможен в течение 14 дней.\", \"Доставка осуществляется по всей России.\", \"Гарантия на технику — 12 месяцев.\" ], \"top_n\": 2 }" ``` > [!NOTE] > > Идентификатор модели берите из `GET /api/v1/models` и подставляйте **как есть**. Состав моделей меняется, поэтому в рабочем коде не зашивайте его литералом. Если передать идентификатор обычной текстовой модели или неизвестное значение, придёт `404` с кодом `model_not_found`. ## Поля запроса | Поле | Тип | Описание | | - | - | - | | `model` | string | Идентификатор модели из каталога с `capabilities`, содержащим `"rerank"`. Обязательно | | `query` | string | Запрос, относительно которого оценивается релевантность. Обязательно | | `documents` | array | Документы для ранжирования: массив строк или массив объектов. Обязательно; пустой массив не принимается | | `documents[]` | string или object | Строка с текстом документа либо объект вида `{"text": ...}` или `{"image": ...}` | | `top_n` | integer | Сколько лучших документов вернуть. Необязательно; по умолчанию возвращаются все | В одном вызове можно смешивать документы-строки и документы-объекты. Документ-объект несёт либо `text`, либо `image` — визуальную модель, которая умеет читать изображения, можно попросить сравнить картинки с текстовым запросом. ## Ответ `200 OK`: ```json theme={null} theme={null} { "id": "rer-...", "model": "идентификатор-модели", "results": [ { "index": 0, "relevance_score": 0.97, "document": {"text": "Возврат товара возможен в течение 14 дней."} }, { "index": 2, "relevance_score": 0.21, "document": {"text": "Гарантия на технику — 12 месяцев."} } ], "usage": { "search_units": 1, "total_tokens": 150, "cost": 0.00012 } } ``` | Поле | Тип | Описание | | - | - | - | | `results` | array | Документы, упорядоченные от самых релевантных к менее релевантным | | `results[].index` | integer | Позиция документа в массиве `documents` запроса — связывает результат с его документом | | `results[].relevance_score` | number | Оценка релевантности, от 0 до 1 | | `results[].document` | object | Документ, как он пришёл в запросе | | `usage.search_units` | integer | Израсходованные единицы поиска (биллинговая единица части провайдеров) | | `usage.total_tokens` | integer | Суммарные токены, обработанные моделью | | `usage.cost` | number | Сумма, списанная с вашего баланса за вызов. Поле отсутствует, если списание не зафиксировано | С `top_n` возвращаются только первые `top_n` позиций, но оценить модель может весь набор — порядок в `results` остаётся порядком убывания релевантности. ### Стоимость Списание зависит от фактической стоимости вызова. Поле `usage.cost` — сумма, списанная с вашего баланса; оно отсутствует, если списание не зафиксировано. Фактический остаток после вызова проверяйте через `GET /api/v1/balance`. ## Проверки перед вызовом Часть ошибок возвращается до обращения к модели: | Ситуация | Ответ | | - | - | | Нет ключа или ключ недействителен | `401 invalid_api_key` | | Модель не из списка моделей ранжирования | `404 model_not_found` | | Не хватает денег | `402 insufficient_quota` | | Нет `model` или `query`, пустой `documents`, документ без `text` и `image` | `400 invalid_request` | Ошибки приходят в конверте OpenAI — объект `error` с полями `message`, `type`, `param` и `code`. Полная таблица кодов — на странице [Ошибки](https://speshu.ai/docs/errors.md). ## Что дальше > [card] [Каталог моделей](https://speshu.ai/docs/api-reference/models/list.md) > > Фильтр по capabilities и цены моделей > [card] [Эмбеддинги](https://speshu.ai/docs/api-reference/embeddings/create.md) > > Векторный поиск как первый этап отбора > [card] [Баланс](https://speshu.ai/docs/api-reference/other/balance.md) > > Остаток кошелька по валютам > [card] [Ошибки](https://speshu.ai/docs/errors.md) > > Полная таблица кодов ## OpenAPI ````yaml api-reference/openapi.json POST /api/v1/rerank openapi: 3.1.0 info: title: SpeShu.AI API version: 1.0.0 description: >- Единый OpenAI-совместимый API для текстовых моделей, генерации изображений, видео, аудио и музыки. ## Аутентификация Все запросы, кроме `GET /api/v1/models` и `GET /api/v1/media/models`, требуют API-ключ. Ключ передаётся в заголовке `Authorization: Bearer <ключ>` или `X-Api-Key: <ключ>`. ## Ошибки Текстовые эндпоинты (`/chat/completions`, `/responses`, `/messages`) и `/balance` возвращают ошибки в формате OpenAI: ```json { "error": { "message": "...", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } ``` Эндпоинты медиа используют собственный конверт: ```json { "code": 422, "msg": "...", "data": null } ``` Подробности — на странице [Ошибки](/errors). servers: - url: https://speshu.ai description: Production security: - BearerAuth: [] tags: - name: Текст description: Генерация текста и диалог - name: Медиа description: Асинхронные задачи генерации изображений, видео, аудио и музыки - name: Хранилище description: Файлы пользователя - name: Справочник description: Каталог моделей и баланс - name: Аудио description: Синтез и распознавание речи - name: Инструменты description: Поиск в интернете и загрузка страниц paths: /api/v1/rerank: post: tags: - Текст summary: Ранжирование description: >- Оценивает релевантность документов относительно запроса и возвращает их упорядоченным списком. Модель берётся из каталога GET /api/v1/models — у неё в capabilities есть значение "rerank". Списание зависит от фактической стоимости вызова. operationId: createRerank requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRerankRequest' responses: '200': description: Документы, упорядоченные по релевантности. content: application/json: schema: $ref: '#/components/schemas/RerankResponse' '400': $ref: '#/components/responses/OpenAIError' '401': $ref: '#/components/responses/OpenAIError' '402': $ref: '#/components/responses/OpenAIError' '403': $ref: '#/components/responses/OpenAIError' '404': $ref: '#/components/responses/OpenAIError' '422': $ref: '#/components/responses/OpenAIError' '429': $ref: '#/components/responses/OpenAIError' '499': $ref: '#/components/responses/OpenAIError' '500': $ref: '#/components/responses/OpenAIError' '502': $ref: '#/components/responses/OpenAIError' '503': $ref: '#/components/responses/OpenAIError' '504': $ref: '#/components/responses/OpenAIError' components: schemas: CreateRerankRequest: type: object required: - model - query - documents properties: model: type: string description: >- Идентификатор модели из GET /api/v1/models: у неё в capabilities есть значение "rerank". Передаётся как есть. query: type: string description: Запрос, относительно которого оценивается релевантность. documents: type: array items: {} description: >- Документы: строки или объекты вида {"text": ...} / {"image": ...}. Пустой массив не принимается. top_n: type: integer description: Сколько лучших документов вернуть. По умолчанию возвращаются все. user: type: string maxLength: 256 description: Идентификатор пользователя на вашей стороне. Необязательно. RerankResponse: type: object properties: id: type: string model: type: string description: Идентификатор модели. results: type: array description: Документы, упорядоченные по убыванию релевантности. items: type: object properties: index: type: integer description: Позиция документа в массиве documents запроса. relevance_score: type: number description: Оценка релевантности от 0 до 1. document: description: Документ, как он пришёл в запросе. required: - index - relevance_score - document usage: type: object properties: search_units: type: integer description: >- Израсходованные единицы поиска (биллинговая единица части провайдеров). total_tokens: type: integer description: Суммарные токены, обработанные моделью. cost: type: number description: >- Сумма, списанная с вашего баланса за вызов. Отсутствует, если списание не зафиксировано. OpenAIError: type: object properties: error: type: object properties: message: type: string type: type: string examples: - invalid_request_error description: >- `authentication_error` при 401, `rate_limit_error` при 429, `permission_error` при 403, в остальных случаях `invalid_request_error`, `api_error` или `internal_error`. param: type: - string - 'null' code: type: - string - 'null' examples: - invalid_request description: >- Машиночитаемый код: `invalid_api_key`, `unauthorized`, `insufficient_quota`, `rate_limit_exceeded`, `token_limit_exceeded`, `content_too_large`, `limit_exceeded`, `model_not_found`, `no_providers`, `service_unavailable`, `provider_error`, `invalid_request`, `context_length_exceeded`, `internal_error`. required: - message - type required: - error responses: OpenAIError: description: Ошибка в формате OpenAI. content: application/json: schema: $ref: '#/components/schemas/OpenAIError' securitySchemes: BearerAuth: type: http scheme: bearer description: >- API-ключ в формате `sk-...`. Альтернативно — заголовок `X-Api-Key: sk-...` (совместимо с Anthropic SDK). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.