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
}
}再ランキング API リファレンス
bge-reranker-v2-m3 再ランキング API リファレンスとライブプレイグラウンド: /v1/rerank のパラメータ、レスポンス構造、エラーコード表、デバッグノート。
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
}
}Bearer sk-your-api-key を入れて、送信を押してください — 例の本文はすでに入力済みです。パラメータ参照
| パラメータ | 型 | 必須 | 備考 |
|---|---|---|---|
model | string | ✓ | 常にbge-reranker-v2-m3、大文字小文字を区別します(名前を間違えると404ではなく503が返ります) |
query | string | ✓ | 検索クエリです。空文字列を指定すると400 query is required が返ります |
documents | string[] | ✓ | 候補です。プレーンな文字列配列のみです。空の配列を指定すると400が返ります |
top_n | int | 上位N件を返します。省略 / 0 / 負の値の場合はすべて返します。文字列を指定すると400が返ります | |
return_documents | bool | ⚠️ このチャネルでは効果がありません — テキストは常にそのままエコーされます |
max_chunks_per_doc、rank_fields、truncate、…)は、拒否されるのではなく黙って無視されます。
レスポンスの注意事項
{
"results": [
{ "document": { "text": "..." }, "index": 0, "relevance_score": 0.97265625 }
],
"usage": { "prompt_tokens": 70, "total_tokens": 91,
"input_tokens": 0, "output_tokens": 0 }
}
index— あなたが送信したdocuments配列内でのドキュメントの元の位置です。これを使って 自分のドキュメントオブジェクトを参照してください。返されたtextでは一致判定しないでください。relevance_score— 範囲は 0–1 です。単一リクエスト内でのみ比較可能です。クエリ間では比較できず、 クロスリンガルの場合は体系的に低くなります。詳細は 概要のしきい値に関する議論 を参照してください。resultsは常にrelevance_scoreの降順でソートされます。indexの値は完全で一意です。prompt_tokens(クエリは 1 回 + すべてのドキュメントでカウント)とtotal_tokens(クエリは ペアごとにカウント)から使用量を読み取ってください。input_tokens/output_tokensはこのチャネルでは常に 0です。 今回は課金からどのフィールドが課金対象かを確認できませんでした — コンソールの請求書を正として扱ってください。
エラーコード
| HTTP | メッセージ | 原因と対処 |
|---|---|---|
| 400 | query is required | query が未指定、または空の文字列です |
| 400 | documents is required | documents が未指定、または空の配列です |
| 400 | Input should be a valid string | documents にオブジェクトを渡しました。プレーンな文字列を使用してください |
| 400 | cannot unmarshal string into ... top_n of type int | top_n が文字列でした。整数を渡してください |
| 400 | This model's maximum context length is 8192 tokens | 1つの query-document ペアが 8192 tokens を超えています。チャンクに分割して再試行してください |
| 401 | Invalid token. | 不正な API キー、または Authorization ヘッダーがありません |
| 429 | 上流の負荷が飽和しました | 上流のクォータ (TPM 20,000 / RPM 120) に達しました。どちらの原因でも同じメッセージが返ります: ① 同時進行中のリクエストが約 4〜5 を超える; ② 1 分あたりの累積 tokens が 20,000 を超える(1000 候補の単一リクエストだけでもすでに超過します)。同時実行数を 4 に抑え、バックオフを追加し、token の使用量を見積もってください。このクォータは拡張中です — より多い利用量については APIYI サポートへお問い合わせください |
| 503 | Current group ... has no available channels for model | モデル名のスペルミス(大文字小文字を区別します)、またはグループに本当にチャネルがありません。まずスペルを確認してください |
Content-Type: text/plain)、ゲートウェイは model フィールドを読み取らず、空のモデル名のまま同じ 503
を返します。見た目はチャネル障害のようですが、実際は違います。/rerank と /v2/rerank の両方(Cohere v2 SDK の
デフォルト)は Web サイトの HTML ホームページ付きの HTTP 200 を返し、クライアント側では
解析できないレスポンスとして現れます。https://api.apiyi.com/v1/rerank だけが有効なパスです。デバッグノート
候補が3件だけでテストしないでください
候補が3件だけでテストしないでください
クロスリンガルテストで低スコアなのは想定内です
クロスリンガルテストで低スコアなのは想定内です
レイテンシの下限は約2秒あります
レイテンシの下限は約2秒あります
デバッグ中にクォータに達することがあります
デバッグ中にクォータに達することがあります
承認
Add the Authorization: Bearer YOUR_API_KEY request header
ボディ
Always bge-reranker-v2-m3 (case-sensitive; a wrong name returns 503)
"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.
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.
true
このページは役に立ちましたか?