Rerank documents: bge-reranker-v2-m3
curl --request POST \
--url https://api.apiyi.com/v1/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"model": "bge-reranker-v2-m3",
"query": "What are the must-see attractions in Hangzhou?",
"documents": [
"West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.",
"The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.",
"Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples."
]
}
EOFimport requests
url = "https://api.apiyi.com/v1/rerank"
payload = {
"model": "bge-reranker-v2-m3",
"query": "What are the must-see attractions in Hangzhou?",
"documents": ["West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.", "The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.", "Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples."]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'bge-reranker-v2-m3',
query: 'What are the must-see attractions in Hangzhou?',
documents: [
'West Lake is Hangzhou\'s most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.',
'The Bund in Shanghai sits along the Huangpu River and is the city\'s signature landmark.',
'Lingyin Temple, in Hangzhou\'s West Lake district, is one of China\'s best-known Buddhist temples.'
]
})
};
fetch('https://api.apiyi.com/v1/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.apiyi.com/v1/rerank",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'bge-reranker-v2-m3',
'query' => 'What are the must-see attractions in Hangzhou?',
'documents' => [
'West Lake is Hangzhou\'s most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.',
'The Bund in Shanghai sits along the Huangpu River and is the city\'s signature landmark.',
'Lingyin Temple, in Hangzhou\'s West Lake district, is one of China\'s best-known Buddhist temples.'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.apiyi.com/v1/rerank"
payload := strings.NewReader("{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"What are the must-see attractions in Hangzhou?\",\n \"documents\": [\n \"West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.\",\n \"The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.\",\n \"Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples.\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/rerank")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"What are the must-see attractions in Hangzhou?\",\n \"documents\": [\n \"West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.\",\n \"The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.\",\n \"Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples.\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.apiyi.com/v1/rerank")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"What are the must-see attractions in Hangzhou?\",\n \"documents\": [\n \"West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.\",\n \"The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.\",\n \"Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples.\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"document": {
"text": "West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda."
},
"index": 0,
"relevance_score": 0.97265625
},
{
"document": {
"text": "Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples."
},
"index": 2,
"relevance_score": 0.1181640625
}
],
"usage": {
"prompt_tokens": 70,
"total_tokens": 91
}
}Rerank
Rerank API Reference
bge-reranker-v2-m3 rerank API reference and live playground: /v1/rerank parameters, response structure, error-code table and debugging notes.
POST
/
v1
/
rerank
Rerank documents: bge-reranker-v2-m3
curl --request POST \
--url https://api.apiyi.com/v1/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"model": "bge-reranker-v2-m3",
"query": "What are the must-see attractions in Hangzhou?",
"documents": [
"West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.",
"The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.",
"Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples."
]
}
EOFimport requests
url = "https://api.apiyi.com/v1/rerank"
payload = {
"model": "bge-reranker-v2-m3",
"query": "What are the must-see attractions in Hangzhou?",
"documents": ["West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.", "The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.", "Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples."]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'bge-reranker-v2-m3',
query: 'What are the must-see attractions in Hangzhou?',
documents: [
'West Lake is Hangzhou\'s most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.',
'The Bund in Shanghai sits along the Huangpu River and is the city\'s signature landmark.',
'Lingyin Temple, in Hangzhou\'s West Lake district, is one of China\'s best-known Buddhist temples.'
]
})
};
fetch('https://api.apiyi.com/v1/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.apiyi.com/v1/rerank",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'bge-reranker-v2-m3',
'query' => 'What are the must-see attractions in Hangzhou?',
'documents' => [
'West Lake is Hangzhou\'s most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.',
'The Bund in Shanghai sits along the Huangpu River and is the city\'s signature landmark.',
'Lingyin Temple, in Hangzhou\'s West Lake district, is one of China\'s best-known Buddhist temples.'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.apiyi.com/v1/rerank"
payload := strings.NewReader("{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"What are the must-see attractions in Hangzhou?\",\n \"documents\": [\n \"West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.\",\n \"The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.\",\n \"Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples.\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/rerank")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"What are the must-see attractions in Hangzhou?\",\n \"documents\": [\n \"West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.\",\n \"The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.\",\n \"Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples.\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.apiyi.com/v1/rerank")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"bge-reranker-v2-m3\",\n \"query\": \"What are the must-see attractions in Hangzhou?\",\n \"documents\": [\n \"West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda.\",\n \"The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.\",\n \"Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples.\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"document": {
"text": "West Lake is Hangzhou's most famous attraction, known for Broken Bridge, Su Causeway and Leifeng Pagoda."
},
"index": 0,
"relevance_score": 0.97265625
},
{
"document": {
"text": "Lingyin Temple, in Hangzhou's West Lake district, is one of China's best-known Buddhist temples."
},
"index": 2,
"relevance_score": 0.1181640625
}
],
"usage": {
"prompt_tokens": 70,
"total_tokens": 91
}
}Use the playground on the right to call the endpoint directly: put
Bearer sk-your-api-key in
Authorization, then hit send — the example body is already filled in.Model capabilities, pricing, measured data and the three gotchas are in the
overview. Recall sizing, chunking and threshold strategy
are in RAG tuning in practice.
Parameter reference
| Parameter | Type | Required | Notes |
|---|---|---|---|
model | string | ✓ | Always bge-reranker-v2-m3, case-sensitive (a wrong name returns 503, not 404) |
query | string | ✓ | The search query. An empty string returns 400 query is required |
documents | string[] | ✓ | Candidates. Plain string array only; an empty array returns 400 |
top_n | int | Return top N. Omitted / 0 / negative all return everything; a string returns 400 | |
return_documents | bool | ⚠️ No effect on this channel — text is always echoed |
max_chunks_per_doc, rank_fields, truncate, …) are silently ignored rather than rejected.
Response notes
{
"results": [
{ "document": { "text": "..." }, "index": 0, "relevance_score": 0.97265625 }
],
"usage": { "prompt_tokens": 70, "total_tokens": 91,
"input_tokens": 0, "output_tokens": 0 }
}
index— the document’s original position in thedocumentsarray you sent. Use it to look up your own document object; don’t match on the returnedtext.relevance_score— range 0–1. Comparable only within a single request. Not comparable across queries, and systematically lower in cross-lingual cases. See the threshold discussion in the overview.resultsis always sorted byrelevance_scoredescending;indexvalues are complete and unique.- Read usage from
prompt_tokens(query counted once + all documents) andtotal_tokens(query counted per pair);input_tokens/output_tokensare always 0 on this channel. This round could not confirm from billing which field is charged — treat the console invoice as authoritative.
Error codes
| HTTP | Message | Cause and fix |
|---|---|---|
| 400 | query is required | query missing or an empty string |
| 400 | documents is required | documents missing or an empty array |
| 400 | Input should be a valid string | You passed objects in documents; use plain strings |
| 400 | cannot unmarshal string into ... top_n of type int | top_n was a string; pass an integer |
| 400 | This model's maximum context length is 8192 tokens | One query-document pair exceeds 8192 tokens; chunk and retry |
| 401 | Invalid token. | Bad API key, or no Authorization header |
| 429 | upstream load saturated | You hit an upstream quota (TPM 20,000 / RPM 120). Both causes return this same message: ① more than ~4–5 concurrent in-flight requests; ② over 20,000 cumulative tokens in a minute (a single 1000-candidate request already exceeds it). Cap concurrency at 4, add backoff, and budget your tokens. This quota is being expanded — contact APIYI support for higher volumes |
| 503 | Current group ... has no available channels for model | Model name misspelled (case-sensitive), or the group genuinely has no channel. Check spelling first |
Suspect the model name first on a 503. If the request body fails to parse (for example
Content-Type: text/plain), the gateway never reads the model field and returns this same 503
with an empty model name — which reads like a channel outage but is not one.A wrong path does not give you a 404. Both
/rerank and /v2/rerank (the Cohere v2 SDK’s
default) return HTTP 200 with the website’s HTML homepage, which surfaces client-side as an
unparseable response. https://api.apiyi.com/v1/rerank is the only valid path.Debugging notes
Don't test with only 3 candidates
Don't test with only 3 candidates
With very few candidates the score gaps are extreme (0.97 for first, 0.12 for second) and tell
you nothing about where the model’s decision boundary sits. Use 10–20 documents including 2–3
deliberate distractors — topically close but not answering the question. That’s what shows you
the score range on your corpus, which is what any threshold has to be based on.
Low scores in cross-lingual tests are expected
Low scores in cross-lingual tests are expected
A Chinese query against English documents may score correct answers at just 0.003–0.3, but
the ordering is right. That’s inherent to the model, not a broken call. Judge by ordering,
not absolute value.
There is a ~2 second latency floor
There is a ~2 second latency floor
Even a single candidate measures around 2 s at P50 — that’s fixed gateway and upstream overhead.
Going from 1 to 100 candidates only moves P50 from 2.0 s to 3.8 s.
So don’t shrink your candidate set to save latency; the payoff is far smaller than expected.
You can hit the quota while debugging
You can hit the quota while debugging
Upstream TPM is only 20,000. Iterating with 100 candidates burns the whole minute’s budget in
about 15 calls and starts returning 429. Debug with 10–20 candidates instead — enough to see the
score distribution, without the quota interrupting you. See the
quota section in RAG tuning.
Authorizations
Add the Authorization: Bearer YOUR_API_KEY request header
Body
application/json
Always bge-reranker-v2-m3 (case-sensitive; a wrong name returns 503)
Example:
"bge-reranker-v2-m3"
The search query. An empty string returns 400
Candidate documents. Plain string array only — passing Cohere-style
[{"text": "..."}] objects returns 400. Cannot be empty. Keep to 100 or fewer.
Return the top N results. Omitting it, or passing 0 or a negative number, returns all. Must be an integer — a string returns 400. Does not affect usage: every candidate is scored regardless.
Example:
2
Whether to echo the document text in results.
Note: this parameter currently has no effect on this channel — document.text
is always echoed. If response size matters, map results back by index yourself
rather than relying on this flag to trim the payload.
Example:
true
Was this page helpful?