Rerank documents by relevance to a query

Rerank a list of documents by their relevance to a given query. Returns the documents sorted by relevance score in descending order. Both the query and each document can be text-only (a plain string) or multimodal (an array of content parts) for compatible models. The request body is limited to 16 MiB total, regardless of content type. A multimodal query or document is further limited to a 12 MiB decoded size per inline base64 image and 2048 content parts each; exceeding any of these returns HTTP 413. Pass images in the query or in a document as a remote http(s) URL instead of inline base64 to stay under the body-size and per-image limits - it does not raise the 2048 content-parts cap.

post

Authorizations

AuthorizationstringRequired

Please provide header value as 'Bearer ' and don't forget to add 'Bearer' HTTP Authorization Scheme before the token.

Body

modelstringRequired

ID of the model to use

queryone ofRequired

The query to rank documents against. Either a plain string, or an array of content parts for a multi-modal query, for example ranking against an image.

stringOptional

or

top_ninteger · min: 1Optional

Number of top results to return. Omit to return all documents. Must be at least 1.

return_documentsbooleanOptional

If true, each result carries the original document text. Defaults to false, in which case match results back to the request using the index field.

Default: false

Responses

200

Successful operation

application/json

400

The request was rejected before it reached a model. The message names the field at fault.

application/json

413

The request body, an inline base64 media payload, or the number of content parts in a single message, query, or document exceeds a documented limit, or a requested image's width or height is above the maximum supported size. Pass large media as a remote http(s) URL instead of inline base64 - a remote URL is fetched directly by the model and does not count against the request body size.

application/json

429

Rate limit exceeded. This response carries no Retry-After header, so back off exponentially and watch X-RateLimit-Remaining-Requests on successful responses to slow down before reaching the limit. Limits are contract-specific.

application/json

500

The request failed on our side. It may or may not have been carried out, so a retry is safe for idempotent calls.

application/json

529

The platform is temporarily overloaded and is shedding load to stay stable. Retry after the number of seconds indicated by the Retry-After header. This is unrelated to your contract's rate limits.

application/json

post/v1/rerank

POST /v1/rerank HTTP/1.1
Host: openai.inference.de-txl.ionos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 217

{
  "model": "Qwen/Qwen3-VL-Reranker-8B",
  "query": "What is the capital of France?",
  "documents": [
    "The capital of France is Paris.",
    "The capital of Brazil is Brasilia.",
    "Lyon is the third-largest city in France."
  ],
  "top_n": 2
}

{
  "id": "text",
  "model": "text",
  "results": [
    {
      "index": 1,
      "document": {
        "text": "text"
      },
      "relevance_score": 1
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "total_tokens": 1
  }
}