Отправка запроса на переранжирование
Отправляет запрос на переранжирование в маршрутизатор переранжирования
OpenAPI
yaml
/openapi/openapi.yaml post /rerank
openapi: 3.1.0
info:
contact:
email: support@openrouter.ai
name: OpenRouter Support
url: https://openrouter.ai/docs
description: OpenAI-compatible API with additional OpenRouter features
license:
name: MIT
url: https://opensource.org/licenses/MIT
title: OpenRouter API
version: 1.0.0
servers:
- description: Production server
url: https://openrouter.ai/api/v1
x-speakeasy-server-id: production
security:
- apiKey: []
tags:
- description: API key management endpoints
name: API Keys
- description: Analytics and usage endpoints
name: Analytics
- description: Anthropic Messages endpoints
name: Anthropic Messages
- description: BYOK endpoints
name: BYOK
- description: Benchmarks endpoints
name: Benchmarks
- description: Chat completion endpoints
name: Chat
- description: Task classification market-share endpoints
name: Classifications
- description: Credit management endpoints
name: Credits
- description: >-
Public OpenRouter usage datasets. Data returned by these endpoints is
licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/):
reuse and republish it, including commercially, with attribution to
OpenRouter.
name: Datasets
- description: Text embedding endpoints
name: Embeddings
- description: Endpoint information
name: Endpoints
- description: Files endpoints
name: Files
- description: Generation history endpoints
name: Generations
- description: Guardrails endpoints
name: Guardrails
- description: Images endpoints
name: Images
- description: Model information endpoints
name: Models
- description: OAuth authentication endpoints
name: OAuth
- description: Observability endpoints
name: Observability
- description: Organization endpoints
name: Organization
- description: Presets endpoints
name: Presets
- description: Provider information endpoints
name: Providers
- description: Rerank endpoints
name: Rerank
- description: OpenAI-compatible Responses API endpoints
name: Responses
- description: SCIM endpoints
name: SCIM
- description: Speech-to-text endpoints
name: STT
x-displayName: Transcriptions
- description: Text-to-speech endpoints
name: TTS
x-displayName: Speech
- description: Video Generation endpoints
name: Video Generation
- description: Workspaces endpoints
name: Workspaces
- description: beta.Analytics endpoints
name: beta.Analytics
externalDocs:
description: OpenRouter Documentation
url: https://openrouter.ai/docs
paths:
/rerank:
post:
tags:
- Rerank
summary: Submit a rerank request
description: Submits a rerank request to the rerank router
operationId: createRerank
requestBody:
content:
application/json:
schema:
description: Rerank request input
example:
documents:
- Paris is the capital of France.
- Berlin is the capital of Germany.
model: cohere/rerank-v3.5
query: What is the capital of France?
top_n: 3
properties:
documents:
description: >-
The list of documents to rerank. Documents may be plain
strings, or structured objects with `text` and/or `image`
for multimodal models.
example:
- Paris is the capital of France.
- Berlin is the capital of Germany.
items:
anyOf:
- type: string
- description: >-
A structured document with optional text and/or image
content. At least one of `text` or `image` must be
provided.
properties:
image:
description: >-
An image associated with the document, as a remote
URL (http/https) or a base64-encoded data URI
(data:image/...).
example: >-
https://upload.wikimedia.org/wikipedia/commons/thumb/8/8b/Phytogenic.png
type: string
text:
description: The document text
example: >-
AI enables robots to perceive, plan, and act
autonomously.
type: string
type: object
description: >-
A document to rerank. Either a plain string, or a
structured object with optional `text` and/or `image`.
minItems: 1
type: array
model:
description: The rerank model to use
example: cohere/rerank-v3.5
type: string
provider:
allOf:
- $ref: '#/components/schemas/ProviderPreferences'
- description: Provider routing preferences for the request.
query:
description: The search query to rerank documents against
example: What is the capital of France?
type: string
top_n:
description: Number of most relevant documents to return
example: 3
minimum: 1
type: integer
required:
- model
- query
- documents
type: object
required: true
responses:
'200':
content:
application/json:
schema:
description: Rerank response containing ranked results
example:
id: gen-rerank-1234567890-abc
model: cohere/rerank-v3.5
results:
- document:
text: Paris is the capital of France.
index: 0
relevance_score: 0.98
usage:
search_units: 1
total_tokens: 150
properties:
id:
description: Unique identifier for the rerank response (ORID format)
example: gen-rerank-1234567890-abc
type: string
model:
description: The model used for reranking
example: cohere/rerank-v3.5
type: string
provider:
description: The provider that served the rerank request
example: Cohere
type: string
results:
description: List of rerank results sorted by relevance
example:
- document:
text: Paris is the capital of France.
index: 0
relevance_score: 0.98
items:
description: A single rerank result
example:
document:
text: Paris is the capital of France.
index: 0
relevance_score: 0.98
properties:
document:
description: >-
The document object echoing the original input (text
and/or image)
properties:
image:
description: >-
The image (URL or data URI) from the original
document
example: https://example.com/image.png
type: string
text:
description: The document text
example: Paris is the capital of France.
type: string
type: object
index:
description: Index of the document in the original input list
example: 0
type: integer
relevance_score:
description: Relevance score of the document to the query
example: 0.98
format: double
type: number
required:
- index
- relevance_score
- document
type: object
type: array
usage:
description: Usage statistics
example:
search_units: 1
total_tokens: 150
properties:
cost:
description: Cost of the request in credits
example: 0.001
format: double
type: number
search_units:
description: Number of search units consumed (Cohere billing)
example: 1
type: integer
total_tokens:
description: Total number of tokens used
example: 150
type: integer
type: object
required:
- model
- results
type: object
text/event-stream:
example: 'data: [DONE]'
schema:
description: Not used for rerank - rerank does not support streaming
type: string
x-speakeasy-sse-sentinel: '[DONE]'
description: Rerank response
'400':
content:
application/json:
example:
error:
code: 400
message: Invalid request parameters
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request - Invalid request parameters or malformed input
'401':
content:
application/json:
example:
error:
code: 401
message: Missing Authentication header
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized - Authentication required or invalid credentials
'402':
content:
application/json:
example:
error:
code: 402
message: >-
Insufficient credits. Add more using
https://openrouter.ai/credits
schema:
$ref: '#/components/schemas/PaymentRequiredResponse'
description: Payment Required - Insufficient credits or quota to complete request
'404':
content:
application/json:
example:
error:
code: 404
message: Resource not found
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found - Resource does not exist
'429':
content:
application/json:
example:
error:
code: 429
message: Rate limit exceeded
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too Many Requests - Rate limit exceeded
'500':
content:
application/json:
example:
error:
code: 500
message: Internal Server Error
schema:
$ref: '#/components/schemas/InternalServerResponse'
description: Internal Server Error - Unexpected server error
'502':
content:
application/json:
example:
error:
code: 502
message: Provider returned error
schema:
$ref: '#/components/schemas/BadGatewayResponse'
description: Bad Gateway - Provider/upstream API failure
'503':
content:
application/json:
example:
error:
code: 503
message: Service temporarily unavailable
schema:
$ref: '#/components/schemas/ServiceUnavailableResponse'
description: Service Unavailable - Service temporarily unavailable
'524':
content:
application/json:
example:
error:
code: 524
message: Request timed out. Please try again later.
schema:
$ref: '#/components/schemas/EdgeNetworkTimeoutResponse'
description: Infrastructure Timeout - Provider request timed out at edge network
'529':
content:
application/json:
example:
error:
code: 529
message: Provider returned error
schema:
$ref: '#/components/schemas/ProviderOverloadedResponse'
description: Provider Overloaded - Provider is temporarily overloaded
components:
schemas:
ProviderPreferences:
additionalProperties: false
description: >-
When multiple model providers are available, optionally indicate your
routing preference.
example:
allow_fallbacks: true
properties:
allow_fallbacks:
description: >
Whether to allow backup providers to serve requests
- true: (default) when the primary provider (or your custom
providers in "order") is unavailable, use the next best provider.
- false: use only the primary/custom provider, and return the
upstream error if it's unavailable.
type:
- boolean
- 'null'
data_collection:
description: >-
Data collection setting. If no available model provider meets the
requirement, your request will return an error.
- allow: (default) allow providers which store user data
non-transiently and may train on it
- deny: use only providers which do not collect user data.
enum:
- deny
- allow
- null
example: allow
type:
- string
- 'null'
enforce_distillable_text:
description: >-
Whether to restrict routing to only models that allow text
distillation. When true, only models where the author has allowed
distillation will be used.
example: true
type:
- boolean
- 'null'
ignore:
description: >-
List of provider slugs to ignore. If provided, this list is merged
with your account-wide ignored provider settings for this request.
example:
- openai
- anthropic
items:
anyOf:
- $ref: '#/components/schemas/ProviderName'
- type: string
type:
- array
- 'null'
max_price:
description: >-
The object specifying the maximum price you want to pay for this
request. USD price per million tokens, for prompt and completion.
properties:
audio:
description: Maximum price in USD per audio unit
type: string
completion:
description: Maximum price in USD per million completion tokens
type: string
image:
description: Maximum price in USD per image
type: string
prompt:
description: Maximum price in USD per million prompt tokens
type: string
request:
description: Maximum price in USD per request
type: string
type: object
only:
description: >-
List of provider slugs to allow. If provided, this list is merged
with your account-wide allowed provider settings for this request.
example:
- openai
- anthropic
items:
anyOf:
- $ref: '#/components/schemas/ProviderName'
- type: string
type:
- array
- 'null'
order:
description: >-
An ordered list of provider slugs. The router will attempt to use
the first provider in the subset of this list that supports your
requested model, and fall back to the next if it is unavailable. If
no providers are available, the request will fail with an error
message.
example:
- openai
- anthropic
items:
anyOf:
- $ref: '#/components/schemas/ProviderName'
- type: string
type:
- array
- 'null'
preferred_max_latency:
$ref: '#/components/schemas/PreferredMaxLatency'
preferred_min_throughput:
$ref: '#/components/schemas/PreferredMinThroughput'
quantizations:
description: A list of quantization levels to filter the provider by.
items:
$ref: '#/components/schemas/Quantization'
type:
- array
- 'null'
require_parameters:
description: >-
Whether to filter providers to only those that support the
parameters you've provided. If this setting is omitted or set to
false, then providers will receive only the parameters they support,
and ignore the rest.
type:
- boolean
- 'null'
sort:
anyOf:
- $ref: '#/components/schemas/ProviderSort'
- $ref: '#/components/schemas/ProviderSortConfig'
- type: 'null'
description: >-
The sorting strategy to use for this request, if "order" is not
specified. When set, no load balancing is performed.
example: price
zdr:
description: >-
Whether to restrict routing to only ZDR (Zero Data Retention)
endpoints. When true, only endpoints that do not retain prompts will
be used.
example: true
type:
- boolean
- 'null'
type:
- object
- 'null'
BadRequestResponse:
description: Bad Request - Invalid request parameters or malformed input
example:
error:
code: 400
message: Invalid request parameters
properties:
error:
$ref: '#/components/schemas/BadRequestResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
UnauthorizedResponse:
description: Unauthorized - Authentication required or invalid credentials
example:
error:
code: 401
message: Missing Authentication header
properties:
error:
$ref: '#/components/schemas/UnauthorizedResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
PaymentRequiredResponse:
description: Payment Required - Insufficient credits or quota to complete request
example:
error:
code: 402
message: Insufficient credits. Add more using https://openrouter.ai/credits
properties:
error:
$ref: '#/components/schemas/PaymentRequiredResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
NotFoundResponse:
description: Not Found - Resource does not exist
example:
error:
code: 404
message: Resource not found
properties:
error:
$ref: '#/components/schemas/NotFoundResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
TooManyRequestsResponse:
description: Too Many Requests - Rate limit exceeded
example:
error:
code: 429
message: Rate limit exceeded
properties:
error:
$ref: '#/components/schemas/TooManyRequestsResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
InternalServerResponse:
description: Internal Server Error - Unexpected server error
example:
error:
code: 500
message: Internal Server Error
properties:
error:
$ref: '#/components/schemas/InternalServerResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
BadGatewayResponse:
description: Bad Gateway - Provider/upstream API failure
example:
error:
code: 502
message: Provider returned error
properties:
error:
$ref: '#/components/schemas/BadGatewayResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
ServiceUnavailableResponse:
description: Service Unavailable - Service temporarily unavailable
example:
error:
code: 503
message: Service temporarily unavailable
properties:
error:
$ref: '#/components/schemas/ServiceUnavailableResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
EdgeNetworkTimeoutResponse:
description: Infrastructure Timeout - Provider request timed out at edge network
example:
error:
code: 524
message: Request timed out. Please try again later.
properties:
error:
$ref: '#/components/schemas/EdgeNetworkTimeoutResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
ProviderOverloadedResponse:
description: Provider Overloaded - Provider is temporarily overloaded
example:
error:
code: 529
message: Provider returned error
properties:
error:
$ref: '#/components/schemas/ProviderOverloadedResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
ProviderName:
enum:
- Modal
- AkashML
- AI21
- AionLabs
- Alibaba
- Ambient
- Baidu
- Amazon Bedrock
- Amazon Nova
- Anthropic
- Arcee AI
- AtlasCloud
- Avian
- Azure
- BaseTen
- BytePlus
- Black Forest Labs
- Cerebras
- Chutes
- Cirrascale
- Claude Platform on AWS
- Clarifai
- Cloudflare
- Cohere
- CoreWeave
- Crucible
- Crusoe
- Darkbloom
- Databricks
- Decart
- Deepgram
- DeepInfra
- DeepSeek
- DekaLLM
- DigitalOcean
- Featherless
- Fireworks
- Fish Audio
- Friendli
- GMICloud
- Google
- Google AI Studio
- Groq
- HeyGen
- Inception
- Inceptron
- InferenceNet
- Ionstream
- Infermatic
- Io Net
- Inferact vLLM
- Inflection
- Liquid
- Mara
- Mancer 2
- Meta
- Minimax
- ModelRun
- Mistral
- Modular
- Moonshot AI
- Morph
- VoyageAI by MongoDB
- NCompass
- Nebius
- Nex AGI
- NextBit
- Novita
- Nvidia
- OpenAI
- OpenInference
- Parasail
- Poolside
- Perceptron
- Perplexity
- Phala
- Recraft
- Reka
- Relace
- Sail Research
- Sakana AI
- SambaNova
- Seed
- SiliconFlow
- Sourceful
- StepFun
- Stealth
- StreamLake
- Switchpoint
- Tencent
- Tenstorrent
- Thinking Machines
- Together
- Upstage
- Venice
- Wafer
- WandB
- Quiver
- Krea
- Runway
- Xiaomi
- xAI
- Z.AI
- FakeProvider
example: OpenAI
type: string
PreferredMaxLatency:
anyOf:
- format: double
type: number
- $ref: '#/components/schemas/PercentileLatencyCutoffs'
- type: 'null'
description: >-
Preferred maximum latency (in seconds). Can be a number (applies to p50)
or an object with percentile-specific cutoffs. Endpoints above the
threshold(s) may still be used, but are deprioritized in routing. When
using fallback models, this may cause a fallback model to be used
instead of the primary model if it meets the threshold.
example: 5
PreferredMinThroughput:
anyOf:
- format: double
type: number
- $ref: '#/components/schemas/PercentileThroughputCutoffs'
- type: 'null'
description: >-
Preferred minimum throughput (in tokens per second). Can be a number
(applies to p50) or an object with percentile-specific cutoffs.
Endpoints below the threshold(s) may still be used, but are
deprioritized in routing. When using fallback models, this may cause a
fallback model to be used instead of the primary model if it meets the
threshold.
example: 100
Quantization:
enum:
- int4
- int8
- fp4
- mxfp4
- nvfp4
- fp6
- fp8
- mxfp8
- fp16
- bf16
- fp32
- unknown
example: fp16
type: string
ProviderSort:
description: The provider sorting strategy (price, throughput, latency)
enum:
- price
- throughput
- latency
- exacto
example: price
type: string
ProviderSortConfig:
description: The provider sorting strategy (price, throughput, latency)
example:
by: price
partition: model
properties:
by:
description: The provider sorting strategy (price, throughput, latency)
enum:
- price
- throughput
- latency
- exacto
- null
example: price
type:
- string
- 'null'
partition:
description: >-
Partitioning strategy for sorting: "model" (default) groups
endpoints by model before sorting (fallback models remain
fallbacks), "none" sorts all endpoints together regardless of model.
enum:
- model
- none
- null
example: model
type:
- string
- 'null'
type: object
BadRequestResponseErrorData:
description: Error data for BadRequestResponse
example:
code: 400
message: Invalid request parameters
properties:
code:
type: integer
message:
type: string
metadata:
additionalProperties: {}
type:
- object
- 'null'
required:
- code
- message
type: object
UnauthorizedResponseErrorData:
description: Error data for UnauthorizedResponse
example:
code: 401
message: Missing Authentication header
properties:
code:
type: integer
message:
type: string
metadata:
additionalProperties: {}
type:
- object
- 'null'
required:
- code
- message
type: object
PaymentRequiredResponseErrorData:
description: Error data for PaymentRequiredResponse
example:
code: 402
message: Insufficient credits. Add more using https://openrouter.ai/credits
properties:
code:
type: integer
message:
type: string
metadata:
additionalProperties: {}
type:
- object
- 'null'
required:
- code
- message
type: object
NotFoundResponseErrorData:
description: Error data for NotFoundResponse
example:
code: 404
message: Resource not found
properties:
code:
type: integer
message:
type: string
metadata:
additionalProperties: {}
type:
- object
- 'null'
required:
- code
- message
type: object
TooManyRequestsResponseErrorData:
description: Error data for TooManyRequestsResponse
example:
code: 429
message: Rate limit exceeded
properties:
code:
type: integer
message:
type: string
metadata:
additionalProperties: {}
type:
- object
- 'null'
required:
- code
- message
type: object
InternalServerResponseErrorData:
description: Error data for InternalServerResponse
example:
code: 500
message: Internal Server Error
properties:
error:
$ref: '#/components/schemas/InternalServerResponseErrorData'
openrouter_metadata:
additionalProperties: {}
type:
- object
- 'null'
user_id:
type:
- string
- 'null'
required:
- error
type: object
BadGatewayResponseErrorData:
description: Error data for BadGatewayResponse
example:
code: 502
message: Provider returned error
properties:
code:
type: integer
message:
type: string
metadata:
additionalProperties: {}
type:
- object
- 'null'
required:
- code
- message
type: object
ServiceUnavailableResponseErrorData:
description: Error data for ServiceUnavailableResponse
example:
code: 503
message: Service temporarily unavailable
properties:
code:
type: integer
message:
type: string
metadata:
additionalProperties: {}
type:
- object
- 'null'
required:
- code
- message
type: object
EdgeNetworkTimeoutResponseErrorData:
description: Error data for EdgeNetworkTimeoutResponse
example:
code: 524
message: Request timed out. Please try again later.
properties:
code:
type: integer
message:
type: string
metadata:
additionalProperties: {}
type:
- object
- 'null'
required:
- code
- message
type: object
ProviderOverloadedResponseErrorData:
description: Error data for ProviderOverloadedResponse
example:
code: 529
message: Provider returned error
properties:
code:
type: integer
message:
type: string
metadata:
additionalProperties: {}
type:
- object
- 'null'
required:
- code
- message
type: object
PercentileLatencyCutoffs:
description: >-
Percentile-based latency cutoffs. All specified cutoffs must be met for
an endpoint to be preferred.
example:
p50: 5
p90: 10
properties:
p50:
description: Maximum p50 latency (seconds)
format: double
type:
- number
- 'null'
p75:
description: Maximum p75 latency (seconds)
format: double
type:
- number
- 'null'
p90:
description: Maximum p90 latency (seconds)
format: double
type:
- number
- 'null'
p99:
description: Maximum p99 latency (seconds)
format: double
type:
- number
- 'null'
type: object
PercentileThroughputCutoffs:
description: >-
Percentile-based throughput cutoffs. All specified cutoffs must be met
for an endpoint to be preferred.
example:
p50: 100
p90: 50
properties:
p50:
description: Minimum p50 throughput (tokens/sec)
format: double
type:
- number
- 'null'
p75:
description: Minimum p75 throughput (tokens/sec)
format: double
type:
- number
- 'null'
p90:
description: Minimum p90 throughput (tokens/sec)
format: double
type:
- number
- 'null'
p99:
description: Minimum p99 throughput (tokens/sec)
format: double
type:
- number
- 'null'
type: object
securitySchemes:
apiKey:
description: API key as bearer token in Authorization header
scheme: bearer
type: http