Overview
The rerank API is compatible with both text and multi-modal requests. This API receives a query and a set of documents, reorders the documents based on their relevance to the query, and returns the reordered results.
API details
Constraints
- The caller must have an API Key. For more information, see Manage AI API Keys.
Request path
POST {BASE_URL}/api/v1/rerank
Request header
Name |
Required |
Example value |
Description |
|---|---|---|---|
| Authorization | Yes | Bearer {token} | Authentication information |
| Content-Type | No | application/json | Request body format |
Request parameters
Path
None
Query
None
Body
Name |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| model | string | Yes | bge-reranker-v2-m3 | The name of the reranking model |
| query | string | Yes | What is artificial intelligence? | The query text |
| documents | array | Yes | ["Document 1 content", "Document 2 content"] | The list of documents to be sorted |
| input | object | No | - | Input object (used for multi-modal requests) |
| top_n | integer | No | 5 | The number of most relevant results to return. Defaults to returning all results. |
| return_documents | boolean | No | false | Whether to include the original document content in the response |
| parameters | object | No | - | Model-specific parameter configuration |
Response
Response parameters
Name |
Type |
Description |
|---|---|---|
| success | boolean | Indicates whether the request was successful |
| code | string | The return code |
| message | string | The return message |
| data | object | The business return data |
data
Name |
Type |
Description |
|---|---|---|
| results | array | The list of reranked results, each containing the document index and relevance score |
Request example
curl --request POST '{BASE_URL}/api/v1/rerank' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
"model": "bge-reranker-v2-m3",
"query": "What is artificial intelligence?",
"documents": ["Artificial intelligence is a new technological science that studies, develops, and applies theories, methods, technologies, and systems to simulate, extend, and enhance human intelligence.", "Machine learning is a branch of artificial intelligence that enables computers to learn without explicit programming."],
"top_n": 2,
"return_documents": false
}'
Response example
{
"success": true,
"code": "200",
"message": "successful",
"data": {
"results": [
{
"index": 0,
"relevance_score": 0.95
},
{
"index": 1,
"relevance_score": 0.82
}
]
}
}