A rerank model re-scores documents returned by initial retrieval, surfacing the most relevant results at the top.
Model overview
ImportantThe gte-rerank model will be discontinued on May 30, 2026. Switch to qwen3-rerank.
Singapore
Model | Max documents | Max input tokens per item | Max input tokens per request | Supported languages | Scenarios |
|---|---|---|---|---|---|
qwen3-rerank | 500 | 4,000 | 120,000 | Over 100 major languages, such as Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian |
|
Beijing
Model | Max documents | Max input tokens per item | Max input tokens per request | Supported languages | Scenarios |
|---|---|---|---|---|---|
qwen3-vl-rerank | Text: 100 Image: 40 Video: 4 | 8,000 | 120,000 | 33 major languages, such as Chinese, English, Japanese, Korean, French, and German |
|
gte-rerank-v2 | 500 | 4,000 | 30,000 | Over 50 languages, such as Chinese, English, Japanese, Korean, Thai, Spanish, French, Portuguese, German, Indonesian, and Arabic |
|
- Max input tokens per item: Maximum tokens 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 documents per request. For qwen3-vl-rerank, the limit varies by document type (text, image, video, or mixed).
- Max input tokens per request: Calculated as
Query Tokens × Number of documents + Total document tokens. Must not exceed the per-request limit.
Input limitations
Model | Image | Video |
|---|---|---|
qwen3-vl-rerank | JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, and SGI (URL or Base64 supported) | MP4, AVI, and MOV (URL only) |
Prerequisites
Obtain an API key and set the API key as an environment variable. To use the SDK: install the DashScope SDK.
HTTP
Replace {WorkspaceId} with your actual workspace ID.
This section describes the DashScope HTTP API.
qwen3-rerankandqwen3.7-text-rerankalso support the OpenAI-compatible API. See OpenAI-compatible API.
RequestRequest headersContent-Type The content type of the request. Must be Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. Request bodymodel The model name. Supported values: qwen3-rerank, gte-rerank-v2, qwen3-vl-rerank. input Input content.
parameters Optional parameters.
| qwen3-rerank
qwen3-vl-rerankText query Image query gte-rerank-v2dashscope CLICall via the dashscope command line. ImportantThe SDK Expert interactive assistant can accomplish the same development and troubleshooting via natural language, see DashScope SDK Expert.For the complete region table, see Base URL overview. |
Responserequest_id Unique request identifier for tracing and troubleshooting. output Task output. usage Token usage statistics. code Error code. Returned only for failed requests. See Error codes. message Detailed error message. Returned only for failed requests. See Error codes. | Successful responseFailed responseIf a request fails, |
OpenAI-compatible API
qwen3-rerank and qwen3.7-text-rerank can be called through the OpenAI-compatible API. gte-rerank-v2 and qwen3-vl-rerank are not supported and return a model_not_supported error.
Endpoint: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks
Differences from the DashScope HTTP API:
- The request body is flat.
query,documents,top_n,instruct, andreturn_documentsare top-level fields alongsidemodel, instead of being nested ininputandparameters. - The ranked results are in the
resultsarray of the response. Each item containsindex(the position of the document in the request) andrelevance_score. Whenreturn_documentsistrue, each item also containsdocument.text.
Sample request
curl --request POST \
--url https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "qwen3-rerank",
"query": "What is a rerank model",
"documents": [
"Rerank models are widely used in search engines and recommendation systems",
"Quantum computing is a frontier field of computer science"
],
"top_n": 2,
"return_documents": true
}'
Sample response
{
"object": "list",
"results": [
{
"document": {
"text": "Rerank models are widely used in search engines and recommendation systems"
},
"index": 0,
"relevance_score": 0.8369123119638817
},
{
"document": {
"text": "Quantum computing is a frontier field of computer science"
},
"index": 1,
"relevance_score": 0.2453528429428607
}
],
"model": "qwen3-rerank",
"id": "f55bad52-5f1a-9db2-a915-57ef33e94664",
"usage": {
"total_tokens": 66
}
}
For Python and Node.js examples, see Rerank.
Use the SDK
Example
Call the rerank model API.
SDK parameter names match the HTTP API, but the structure differs. HTTP uses nested
inputandparametersobjects; the SDK uses a flat structure.
import os
import dashscope
# The following configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
# If you have not set an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
def text_rerank():
resp = client.rerank.create(
model="gte-rerank-v2",
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."
],
top_n=2,
return_documents=True
)
print(resp)
if __name__ == '__main__':
text_rerank()
Use qwen3-vl-rerank for multimodal reranking with an image query.
import os
import dashscope
import json
# The following configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
# If you have not set an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
def vl_rerank():
resp = client.rerank.create(
model="qwen3-vl-rerank",
query={"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
documents=[
{"text": "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance."},
{"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
{"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"}
],
top_n=2,
return_documents=True
)
print(json.dumps(resp.model_dump(), ensure_ascii=False, indent=4))
if __name__ == '__main__':
vl_rerank()
Sample output
NoteSDK 2.0 returns a structured response object. Access rerank results via resp.results (resp.results[i].index / .relevance_score / .document); failed requests raise a DashScopeError exception.
{
"request_id": "4b0805c0-6b36-490d-8bc1-4365f4c89905",
"output": {
"results": [
{
"index": 0,
"relevance_score": 0.9334521178273196,
"document": {
"text": "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance."
}
},
{
"index": 2,
"relevance_score": 0.34100082626411193,
"document": {
"text": "The development of pre-trained language models has brought new advancements to rerank models."
}
}
]
},
"usage": {
"total_tokens": 79
}
}
Error codes
If the model call fails and returns an error message, see Error codes for resolution.