Rerank

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. We recommend switching to the qwen3-rerank model. For more information, see the official announcement.

Model	Max documents	Max input tokens per item	Max input tokens per request	Supported languages	Scenarios
qwen3.7-text-rerank	500	30,000	120,000 (recommended)	201 major languages and dialects, including Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian	Text semantic retrieval Retrieval-augmented generation (RAG) applications
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	Image clustering Cross-modal search Image retrieval
qwen3-rerank	500	4,000	120,000	Over 100 major languages, such as Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian	Text semantic retrieval Retrieval-augmented generation (RAG) applications
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.

Request

Request headers

Content-Type string (Required)

The content type of the request. Must be application/json.

Authorization string (Required)

Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Request body

model string (Required)

The model name. Supported values: qwen3.7-text-rerank, qwen3-rerank, gte-rerank-v2, qwen3-vl-rerank.

input object (Required)

Input content.

Nest query and documents in the input object.

Properties

query string | object (Required)

Query text (max 4,000 tokens).

qwen3-vl-rerank supports two query formats:

String format: Pass a text string directly, e.g., "query": "What is a rerank model?".
Object format: Pass a dictionary specifying modality type and value as {"modality type": "input content"}. Supported types: text and image.
- Text query: "query": {"text": "What is a text rerank model?"}
- Image query: "query": {"image": "Image URL or Base64-encoded string"}

documents array (Required)

Candidate documents to sort. Each element is a string.

qwen3-vl-rerank accepts a dictionary or string per element: {"modality type": "text/image URL/video URL"}. Supported types: text, image, video.

Text: Key is text, value is a string. A plain string without a dictionary wrapper also works.
Image: Key is image, value is a URL or Base64 Data URI (data:image/{format};base64,{data}, where {format} is jpeg/png and {data} is the encoded string).
Video: Key is video, value must be a publicly accessible URL.

parameters object (Optional)

Optional parameters.

Nest top_n and instruct in the parameters object.

Properties

top_n int (Optional)

Number of top-ranked documents to return. Default: all documents. Values exceeding total documents return all.

return_documents bool (Optional)

Whether to include document text in results. Default: false. Supported models: gte-rerank-v2, qwen3-vl-rerank, qwen3-rerank.

instruct string (Optional)

Custom sorting instruction. Applies to qwen3.7-text-rerank, qwen3-rerank, and qwen3-vl-rerank. Guides the model to apply different sorting policies. Examples:

Q&A retrieval task (default): "Given a web search query, retrieve relevant passages that answer the query."
- Focus: Find answers. Model prioritizes whether a document answers the query.
- Example: Query "How to prevent a cold?" - Document "Washing hands frequently prevents colds" scores high; "A cold is a common illness" scores low (topically relevant but doesn't answer).
Semantic similarity sorting task: "Retrieve semantically similar text."
- Focus: Determine semantic equivalence. Model evaluates whether query and document have consistent core meaning, regardless of wording or structure.
- Example: In FAQ scenarios, "How do I change my password?" and "What if I forget my password?" are semantically similar (high score). Model focuses on whether both reflect the same user intent.

Write instructions in English. Default: Q&A retrieval task. More instructions are available in the model repository.

fps float (Optional)

qwen3-vl-rerank only. Controls video frame extraction count. Smaller values = fewer frames. Range: 0-1 (default: 1.0).

qwen3.7-text-rerank

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3.7-text-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": {
        "top_n": 2,
        "instruct": "Given a web search query, retrieve relevant passages that answer the query."
    }
}'

qwen3-rerank

curl --request POST \
  --url https://{WorkspaceId}.cn-beijing.maas.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": {
            "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?"
        },
        "parameters": {
            "top_n": 2,
            "instruct": "Given a web search query, retrieve relevant passages that answer the query."
        }
}'

qwen3-vl-rerank

Text query

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3-vl-rerank",
    "input":{
         "query": {"text": "What is a rerank model?"},
         "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"}
         ]
    },
    "parameters": {
        "return_documents": true,
        "top_n": 2,
        "fps": 1.0
    }
}'

Image query

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3-vl-rerank",
    "input":{
         "query": {"image": "Image URL or Base64"},
         "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"}
         ]
    },
    "parameters": {
        "return_documents": true,
        "top_n": 2,
        "fps": 1.0
    }
}'

gte-rerank-v2

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "gte-rerank-v2",
    "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
    }
}'

dashscope CLI

Call via the dashscope command line.

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your Workspace ID, and cn-beijing with the corresponding region (Singapore: ap-southeast-1, US East: us-east-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
dashscope rerank create -m gte-rerank-v2 -q "Machine learning" -d "Machine learning is a branch of AI" -d "The weather is nice today"

ImportantThe SDK Expert interactive assistant can accomplish the same development and troubleshooting in natural language. See

DashScope SDK Expert.

For the complete region table, see Base URL overview.

Response

request_id string

Unique request identifier for tracing and troubleshooting.

output object

Task output.

Properties

results array

Sorting results, ordered by relevance_score descending.

Properties

document dict

Original document object. Returned only when return_documents is true. Format: {"text": "Original document text"}.

index int

Document index in the input documents array.

relevance_score double

Semantic relevance between document and query. Range: 0.0-1.0 (higher = more relevant).

NoteScores are relative to the current request and cannot be compared across requests.

usage object

Token usage statistics.

Properties

prompt_tokens int

Returned only by qwen3.7-text-rerank. The total number of tokens in the request input.

total_tokens int

The total tokens consumed by the request, used for billing and audit.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

Successful response

qwen3.7-text-rerank

{
    "output": {
        "results": [
            {
                "index": 0,
                "relevance_score": 0.9334521178273196
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193
            }
        ]
    },
    "usage": {
        "prompt_tokens": 79,
        "total_tokens": 79
    },
    "request_id": "85ba5752-1900-47d2-8896-23f99b13f6e1"
}

qwen3-rerank

{
    "output": {
        "results": [
            {
                "index": 0,
                "relevance_score": 0.9334521178273196
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193
            }
        ]
    },
    "request_id": "85ba5752-1900-47d2-8896-23f99b13f6e1",
    "usage": {
        "total_tokens": 79
    }
}

qwen3-vl-rerank / gte-rerank-v2

{
    "output": {
        "results": [
            {
                "document": {
                    "text": "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance."
                },
                "index": 0,
                "relevance_score": 0.9334521178273196
            },
            {
                "document": {
                    "text": "The development of pre-trained language models has brought new advancements to rerank models."
                },
                "index": 2,
                "relevance_score": 0.34100082626411193
            }
        ]
    },
    "usage": {
        "total_tokens": 79
    },
    "request_id": "85ba5752-1900-47d2-8896-23f99b13f6e1"
}

Failed response

If a request fails, code and message indicate the error cause.

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

Use the SDK

Example

The following example shows how to call the document rerank model API.

SDK parameter names match the HTTP API, but the structure differs. HTTP uses nested input and parameters objects; the SDK uses a flat structure.

import os
import dashscope
# This 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 this line with your Model Studio API key: api_key="sk-xxx",
    # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/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="qwen3.7-text-rerank",
        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=10,
        instruct="Given a web search query, retrieve relevant passages that answer the query."
    )
    print(resp)

if __name__ == '__main__':
    text_rerank()

The following example shows how to use the qwen3-vl-rerank model for multimodal reranking with an image as the query.

import os
import dashscope
import json
# This 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 this line with your Model Studio API key: api_key="sk-xxx",
    # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/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. You can access the rerank results through resp.results (resp.results[i].index / .relevance_score / .document); failed requests throw a DashScopeError exception.

{
    "request_id": "4b0805c0-6b36-490d-8bc1-4365f4c89905",
    "output": {
        "results": [
            {
                "index": 0,
                "relevance_score": 0.9334521178273196
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193
            }
        ]
    },
    "usage": {
        "prompt_tokens": 79,
        "total_tokens": 79
    }
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

Rate limiting

For the conditions that trigger model rate limiting, see Rate Limits.