tencent cloud

Reranking Model

Download
Focus Mode
Font Size
Last updated: 2026-11-17 14:27:53
AI-Translated & Reviewed

Overview

The CMR Rerank API ranks a set of candidate content by relevance based on the query, and is suitable for scenarios such as search result optimization and knowledge base search. You can call Rerank models from different vendors by using the unified API and a CMR API Key. The ranking results and scores are provided by the selected model. Text, images, and videos use the same API:
POST /v1/rerank
Request Type
query Content
Candidate List (documents)
Text reranking
A piece of text
Multiple text segments
Image query
An image
Text, image, or video candidates
Video query
A video
Text, image, or video candidates
Mixed candidate reranking
Text, image, or video
Candidate list containing different content types
Whether image, video, and mixed candidates are available depends on the support of the selected model. Each request provides only one query, and each candidate contains only one piece of text, one image, or one video.

Prerequisites

1. It is recommended to read Usage Constraints and Supported Model Providers in advance for relevant information.
2. A CMR instance has been created. For detailed instructions, see Creating a CMR Instance.
3. A BYOK instance has been created. For detailed instructions, see Creating a BYOK Instance.
4. A CMR API key has been created. For detailed instructions, see Creating a CMR API Key.
5. Rerank model association and CMR policy configuration have been completed. For detailed instructions, see Configuring Model Scheduling Management.

API Endpoint and Authentication

Request URL

POST {CMR_BASE_URL}/v1/rerank
CMR_BASE_URL is the instance access address displayed in the console. Use the CMR model name and CMR API Key for requests. You do not need to provide the vendor's API address or API Key.

Request Header

Header
Required
Description
Authorization
Yes
Bearer <CMR_API_KEY>
Content-Type
Yes
Fixed as application/json.

Quick Start

Replace the access address, API Key, and model name in the example with your own configuration.

cURL

curl --request POST "${CMR_BASE_URL}/v1/rerank" \\
--header "Authorization: Bearer ${CMR_API_KEY}" \\
--header "Content-Type: application/json" \\
--data '{
"model": "cmr-text-rerank",
"query": "How do I install the product?",
"documents": [
"Product refund rules.",
"Secure the base first, then connect the power."
]
}'

Python

import os
import requests

documents = [
"Product refund rules.",
"Secure the base first, then connect the power.",
]

response = requests.post(
f"{os.environ['CMR_BASE_URL']}/v1/rerank",
headers={
"Authorization": f"Bearer {os.environ['CMR_API_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "cmr-text-rerank",
"query": "How do I install the product?",
"documents": documents,
},
timeout=30,
)
response.raise_for_status()

for item in response.json()["results"]:
print(item["relevance_score"], documents[item["index"]])

Request Parameters

Common Request Parameters

Parameter
Type
Required
Description
model
string
Yes
CMR model name or model alias. Available values are subject to the models associated in the console.
query
string | object
Yes
Current query. For text, enter a string. For an image, enter {"image":"..."}. For a video, enter {"video":"..."}.
documents
array
Yes
Candidate list to be sorted. Each item can be a text string, an image object, or a video object.
top_n
integer
No
Returns the top N items with the highest relevance. The value range and the behavior when this parameter is not specified are subject to the selected model.
return_documents
boolean
No
Whether to request the model to return candidate content. Whether the content is actually returned depends on the model.
instruct
string
No
Sorting requirements, for example, "prioritize content that provides specific installation steps"
Whether an optional parameter takes effect depends on the selected model. For unspecified optional parameters, CMR does not automatically fill in default values.

Text Input

For query and text candidates, directly provide strings. For the simplest request, see Quick Start. The following demonstrates how to add optional parameters to limit the number of results, request candidate content in the response, and specify ranking requirements when these optional parameters are supported by the selected model:
{
"model": "cmr-text-rerank",
"query": "How do I install the product?",
"documents": [
"Product refund rules.",
"Secure the base first, then connect the power."
],
"top_n": 1,
"return_documents": true,
"instruct": "Prioritize content that provides specific installation steps."
}

Image and Video Input

Content
Format
Fillable Location
Text
Installation steps
query or documents[]
Figure
{"image":"Image URL or Data URI"}
query or documents[]
Video
{"video":"Video URL"}
query or documents[]
Example of image query and mixed candidates:
{
"model": "cmr-multimodal-rerank",
"query": {"image": "https://example.com/product.png"},
"documents": [
"Product refund rules.",
"Secure the base first, then connect the power.",
{"image": "https://example.com/manual.png"},
{"video": "https://example.com/tutorial.mp4"}
]
}
For video queries, change query to:
{"video": "https://example.com/question.mp4"}
Media URLs and content formats must meet the requirements of the selected model. The availability and effectiveness of video queries must also be confirmed based on the model. Directly entered URL strings are treated as text. For images and videos, use the object format specified in the table.

Provider Custom Request Parameters

A CMR instance enables parameter conversion by default and passes through vendor-defined parameters by default. Place parameters in the request as required by the vendor. You do not need to configure allowlisting for each parameter. If parameter filtering rules are configured for the instance, parameters are processed according to those rules. For example, if the selected model supports return_raw_scores, you can make a request as follows:
{
"model": "cmr-text-rerank",
"query": "How do I install the product?",
"documents": ["Product refund rules.", "Secure the base first, then connect the power."],
"return_raw_scores": true
}
To set default values, modify parameter values, or filter fields, you can configure rules in the parameter conversion settings of the target CMR instance. When configuring through the management API, use CreateParamTranslationConfig to save and TestParamTranslationConfig to preview. For Rerank rules, set the endpoint to rerank. The names, tiers, and values of custom parameters are subject to the vendor documentation. After changing the model or vendor, confirm that these parameters still apply.

Response Parameters

Common Response Parameters

Parameter
Type
Returned or Not
Description
id
string
Yes
Identifier of this request.
created
integer
Yes
Response creation time, which is a Unix timestamp in seconds.
object
string
Yes
Fixed to list
model
string
Yes
Name of the CMR logical model that was successfully called in this request
results
object[]
Yes
List of reranked results
usage
object
No
Usage information returned by the model. If not provided, this field is not returned.

Response result

Parameter
Type
Returned or Not
Description
results[].index
integer
Yes
Index of the candidate in the requested documents, starting from 0, not the ranking position.
results[].relevance_score
number
Yes
Relevance score returned by the model
results[].document
string | object
No
Candidate content returned by the model: text as a string, image as {"image":"..."}, video as {"video":"..."}.
CMR preserves the order and scores returned by the model. Scores from different models may not be directly comparable and should not be treated as probabilities. Whether the document field appears depends on the actual model response. Even if return_documents=true is set, it may not be returned. If you need the original candidates, use index to look up documents[index] in the request.

Provider Custom Response Parameters

In addition to the standard response fields described above, CMR also passes through custom fields actually returned by the vendor, such as request_id and additional fields in result items or usage information, preserving their content and internal structure without requiring extra configuration. Information that has been converted to standard fields is not returned again. The meaning of custom fields is subject to the vendor documentation. After the model or vendor is changed, these fields may no longer be returned or their meaning may change.

Response Example

The following example illustrates the field format. Scores and usage are subject to the actual response.

Text Result

{
"id": "rerank-7f3a2c10",
"created": 1788969600,
"object": "list",
"model": "cmr-text-rerank",
"results": [
{
"index": 1,
"relevance_score": 0.91,
"document": "Secure the base first, then connect the power."
}
],
"usage": {
"prompt_tokens": 60,
"completion_tokens": 0,
"total_tokens": 60
}
}
index=1 indicates that the result corresponds to the second candidate in the request. If the model does not return candidate content or usage, the corresponding fields are omitted from the response.

Image Result

{
"id": "rerank-a1b2c3d4",
"created": 1788969600,
"object": "list",
"model": "cmr-multimodal-rerank",
"results": [
{
"index": 2,
"relevance_score": 0.91,
"document": {"image": "https://example.com/manual.png"}
}
],
"usage": {
"prompt_tokens": 147,
"total_tokens": 829,
"prompt_tokens_details": {"image_tokens": 682}
}
}

Error Response

When a request fails, CMR returns a unified error format:
{
"error": {
"message": "Invalid request parameter",
"type": "invalid_request_error",
"param": null,
"code": "400"
}
}
Parameter
Description
error.message
Error description
error.type
Error type
error.param
Related request parameter. It may be empty when it cannot be located.
error.code
Error code. Subject to the actual response.
Common HTTP status codes:
HTTP Status Code
Common Cause
Handling Recommendation
400
Invalid request format, or the model does not support the current parameters or content type.
Check and correct the request.
401
Invalid API Key or authentication failure.
Check the API Key and vendor credentials.
403
Invalid authentication header or no access permission.
Check Authorization and model permissions.
404
The model, resource, or API does not exist.
Check the model name and access configuration.
408 / 504
Request timeout.
Retry later when business allows.
429
Request rate limiting or insufficient quota.
Refer to Retry-After and retry after reducing the request rate.
500 / 502 / 503
Service exception, connection failure, or abnormal response content.
Retry later. If failures persist, record the request ID and contact support.


Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback