⌘K

Qwen3-Rerank

qwen3-rerank

Text reranking model for search engines and recommendation systems. Ranks candidate texts based on semantic relevance to queries. Supports custom task instructions for question-answering and semantic similarity tasks.

Authentication

authorization string required

All APIs require authentication via Bearer Token.

Get API Key:

Visit API Key Management Page to get your API Key.

Usage:

Add to request header:

Authorization: Bearer YOUR_API_KEY

Parameters

model string required

Model ID to use for the request.

Value: qwen3-rerank

query string required

Query content for ranking. Maximum length cannot exceed 4,000 tokens.

documents array required

List of candidate documents to be ranked. Each element is a text string.

top_n integer

Number of top-ranked documents to return. If not specified, all documents are returned. If the specified value exceeds the total number of documents, all documents will be returned.

instruct string

Custom ranking task instruction. Guides the model to adopt different ranking strategies.

Question-Answering Retrieval (Default):
"Given a web search query, retrieve relevant passages that answer the query."

Focus: Finding answers to questions. The model prioritizes evaluating whether documents answer the query.
Example: For query “How to prevent colds?”, document “Washing hands frequently is an effective way to prevent colds” scores high; while “Colds are a common disease” scores lower despite being topically related.

Semantic Similarity Ranking:
"Retrieve semantically similar text."

Focus: Judging semantic equivalence. The model evaluates whether the core meanings of query and document are consistent, regardless of specific wording.
Example: In FAQ scenarios, user query “How to change password?” and candidate question “Forgot password, what to do?” are semantically similar and should score high.

Recommended to use English. If not specified, defaults to question-answering retrieval task.

return_documents boolean

Whether to return original document text in ranking results. Default is false to reduce network transmission overhead.

Response Format

request_id string

Unique request identifier for tracing and troubleshooting.

output object

Task output information.

results array

Ranking results list, ordered by relevance_score from high to low.

index integer

Original index position in the input documents list.

relevance_score number

Semantic relevance score between document and query, ranging from 0.0 to 1.0. Higher scores indicate stronger relevance.

Note: This score is relative within the current request and is used for ranking documents within this request. It should not be used as an absolute value for cross-request comparison.

document object

Original document object. Only returned when request parameter return_documents is true. Structure: {"text": "document text"}.

usage object

Token usage statistics.

total_tokens integer

Total number of tokens consumed in this request.