DashScope reranking | Qwen Cloud

POST

/services/rerank/text-rerank/text-rerank

curl --request POST \
  --url https://dashscope-intl.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "qwen3-rerank",
  "input": {
    "query": "What is a rerank model?",
    "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."
    ]
  },
  "parameters": {
    "return_documents": true,
    "top_n": 2
  }
}'

{
  "output": {
    "results": [
      {
        "document": {
          "text": "<string>"
        },
        "index": 0,
        "relevance_score": 0.9334521178273196
      }
    ]
  },
  "usage": {
    "total_tokens": 0
  },
  "request_id": "85ba5752-1900-47d2-8896-23f99b13f6e1"
}

Rerank documents by semantic relevance to a query using qwen3-rerank. Uses a nested request structure with input and parameters wrappers.

Before you begin: get an API key, set it as an environment variable, and install the DashScope SDK if you use the SDK.

Endpoint

HTTP: POST https://dashscope-intl.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank
SDK base_http_api_url: https://dashscope-intl.aliyuncs.com/api/v1

Model overview

Model	Max Documents	Max Tokens/Doc	Max Request Tokens	Languages	Price (per 1M tokens)	Free Quota	Use Cases
qwen3-rerank	500	4,000	120,000	100+ languages	$0.1	1M tokens (valid for 90 days)	Text semantic search, RAG

Parameter definitions:

Max Tokens/Doc: Maximum token count per query or document. Content exceeding this limit is truncated, which may affect ranking accuracy.
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

Qwen Cloud API Key. Create one in the console.

Body

application/json

enum<string>

required

Model name. Must be qwen3-rerank.

Available options:qwen3-rerank

Example:qwen3-rerank

object

required

Input data containing the query and documents to rank.

Show child attributes

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.

object

Optional parameters for the reranking request. The parameters wrapper is optional — top_n and instruct can be placed at the same level as model.

Show child attributes

integer

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

Example:2

Required range:x >= 1

boolean

defaultfalse

Include original document text in results. Default: false.

Example:true

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

object

Output wrapper containing ranked results.

Show child attributes

object[]

Ranked results, sorted by relevance_score descending.

Show child attributes

object

Original document. Only returned when return_documents is true.

Show child attributes

string

Text content of the document.

integer

Original position in the input documents list.

Example:0

number

Relevance score between 0.0 and 1.0. Higher means more relevant. This is a relative score for the current request and should not be compared across requests.

Example:0.9334521178273196

object

Token usage statistics.

Show child attributes

integer

Total tokens consumed by this request.

string

Unique request identifier.

Example:85ba5752-1900-47d2-8896-23f99b13f6e1

​Endpoint

​Model overview

Authorizations

Body

Response

Endpoint

Model overview