Skip to main content
QwenCloud home page
Docs
Reranking

OpenAI compatible reranking

OpenAI-compatible reranking API

POST
https://ap-southeast-1.maas.qwencloudapi.com/compatible-api/v1/reranks
qwen3-rerank
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl --request POST \
  --url https://ap-southeast-1.maas.qwencloudapi.com/compatible-api/v1/reranks \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
        "model": "qwen3-rerank",
        "documents": [
                "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance.",
                "Quantum computing is a cutting-edge field of computer science.",
                "The development of pre-trained language models has brought new advancements to rerank models."
        ],
        "query": "What is a rerank model?",
        "top_n": 2,
        "instruct": "Given a web search query, retrieve relevant passages that answer the query."
}'
{
  "id": "<string>",
  "object": "list",
  "model": "qwen3-rerank",
  "results": [
    {
      "document": {
        "text": "<string>"
      },
      "index": 0,
      "relevance_score": 0.9334521178273196
    }
  ],
  "usage": {
    "total_tokens": 0
  }
}
Rerank documents by semantic relevance to a query using qwen3-rerank.
The gte-rerank model was discontinued on May 30, 2026. Switch to qwen3-rerank.
Before you call the API, get an API key and set it as an environment variable. If you use the OpenAI SDK, install it first.
Supported model: qwen3-rerank only.

Endpoint

The following uses the Singapore (ap-southeast-1) endpoint. To use China North 2 (Beijing), replace ap-southeast-1 with cn-beijing and use an API key from that region. Reranking is not available in other regions. See Regions and endpoints.
  • HTTP: POST https://ap-southeast-1.maas.qwencloudapi.com/compatible-api/v1/reranks
  • SDK base_url: https://ap-southeast-1.maas.qwencloudapi.com/compatible-api/v1

Model overview

ModelMax DocumentsMax Tokens/DocMax Request TokensLanguagesUse Cases
qwen3-rerank5004,000120,000100+ languagesText semantic search, RAG
For pricing, see the Model Marketplace. Parameter definitions:
  • Max Tokens/Doc: Maximum token count per query or document. If a query or document exceeds this limit, the API returns an HTTP 400 error and does not truncate the input.
  • Max Documents: Maximum number of documents per request.
  • Max Request Tokens: Calculated as Query Tokens x Document Count + Total Document Tokens. Must not exceed the limit.

Authorizations

​
string
header
required

QwenCloud API Key. Create one in the console.

Body

application/json
​
enum<string>
required

Model name. Must be qwen3-rerank for the text reranking endpoint.

Available options:qwen3-rerank
Example:qwen3-rerank
​
string
required

Query text. Max 4,000 tokens.

Example:What is a reranking model
​
string[]
required

Documents to rank. An array of strings. Max 500 documents.

Example:
[
  "Reranking models are widely used in search engines and recommendation systems to sort candidates by relevance",
  "Quantum computing is a frontier field of computer science",
  "The development of pre-trained language models has brought new advances to reranking"
]
​
integer

Return only the top N results. Defaults to returning all documents.

Example:2
Required range:x >= 1
​
string

Custom ranking task instruction. English recommended. Default behavior is QA retrieval: "Given a web search query, retrieve relevant passages that answer the query."

Example:Given a web search query, retrieve relevant passages that answer the query.

Response

200-application/json
​
string

Unique request identifier.

​
string

Object type. Always list.

Example:list
​
string

Model used for reranking.

Example:qwen3-rerank
​
object[]

Ranked results, sorted by relevance_score descending.

​
object

Token usage statistics.