DashScope reranking

POST

https://ap-southeast-1.maas.qwencloudapi.com/compatible-api/v1/services/rerank/text-rerank/text-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/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 (text) or qwen3-vl-rerank (text, images, and videos). Uses a nested request structure with input and parameters wrappers.

The gte-rerank model was discontinued on May 30, 2026. Switch to qwen3-rerank. This does not apply to gte-rerank-v2, which remains available in China North 2 (Beijing).

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

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/api/v1/services/rerank/text-rerank/text-rerank
SDK base_http_api_url: https://ap-southeast-1.maas.qwencloudapi.com/api/v1

Model overview

Model	Regions	Max Documents	Max Tokens/Doc	Max Request Tokens	Languages	Use Cases
qwen3-rerank	Singapore, China North 2 (Beijing)	500	4,000	120,000	100+ languages	Text semantic search, RAG
gte-rerank-v2	China North 2 (Beijing) only	500	4,000	30,000	50+ languages	Text semantic search, RAG
qwen3-vl-rerank	China North 2 (Beijing) only	Text: 100; image: 40; video: 4	8,000	120,000	33 languages	Multimodal search result reranking (text, image, video)

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. For qwen3-vl-rerank, the limit depends on the document modalities in the 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. qwen3-rerank and gte-rerank-v2 rerank text. qwen3-vl-rerank reranks text, images, and videos. gte-rerank-v2 and qwen3-vl-rerank are available only in China North 2 (Beijing).

Available options:qwen3-rerank,gte-rerank-v2,qwen3-vl-rerank

Example:qwen3-rerank

object

required

Input data containing the query and documents to rank.

Show child attributes

string

required

Query. For qwen3-rerank, a text string (max 4,000 tokens). For qwen3-vl-rerank, a string or an object with a text or image key.

Example:What is a reranking model

(string | object)[]

required

Documents to rank. For qwen3-rerank, an array of strings (max 500 documents). For qwen3-vl-rerank, each element is a string or an object with a text, image, or video key (max 100 text, 40 image, or 4 video documents).

string
object

object

Parameters for the reranking request. Must be wrapped inside this parameters object.

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." Supported by qwen3-rerank and qwen3-vl-rerank.

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

number

default1

qwen3-vl-rerank only. Video frame sampling rate. Smaller values extract fewer frames. Range [0, 1]. Default: 1.0.

Required range:0 <= x <= 1

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