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 |
POST {CMR_BASE_URL}/v1/rerank
Header | Required | Description |
Authorization | Yes | Bearer <CMR_API_KEY> |
Content-Type | Yes | Fixed as application/json. |
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."]}'
import osimport requestsdocuments = ["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"]])
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" |
{"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."}
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[] |
{"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"}]}
{"video": "https://example.com/question.mp4"}
{"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}
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. |
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":"..."}. |
{"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}}
{"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": {"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. |
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. |
Was this page helpful?
You can also Contact sales or Submit a Ticket for help.
Help us improve! Rate your documentation experience in 5 mins.
Feedback