重排序 · TokenToSea 开发者文档

POST https://api.tokentosea.com/v1/rerank

给定一个查询和一组候选文档，返回每个文档的相关性分数与排序。请求字段统一，响应为厂商原生结构。

前提：全能密钥或模型密钥，账户可用余额足以覆盖本次预留。Python 示例需要 pip install requests，Node.js 示例需要 Node.js 18+。

支持的型号#

服务商	型号
千问	`qwen3.7-text-rerank`、`qwen3-rerank`、`qwen3-vl-rerank`、`gte-rerank-v2`
智谱	`rerank`

截至 2026-10-21，以 GET /v1/models 为准。只支持非流式（JSON）响应，按输入 token 计费。

请求体#

参数	类型	必填	说明
`model`	string	必填	型号 ID
`query`	string	必填	查询文本
`documents`	string[]	必填	候选文档
`top_n`	integer	可选	只返回前 N 个结果
`return_documents`	boolean	可选	是否在结果中附带原文
`parameters`	object	可选	千问：其他厂商原生参数

千问型号的 top_n、return_documents 会转换为厂商的 parameters；智谱的请求体原样转发，其他字段以智谱文档为准。

响应#

千问响应示例

{
  "output": {
    "results": [
      { "index": 0, "relevance_score": 0.93 }
    ]
  },
  "usage": { "total_tokens": 42 },
  "request_id": "…"
}

index 是文档在 documents 中的位置。千问返回 DashScope 原生结构（结果位于 output.results）；智谱返回其原生结构。字段以厂商文档为准。

示例#

curl https://api.tokentosea.com/v1/rerank \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gte-rerank-v2",
    "query": "什么是向量检索？",
    "documents": ["向量检索通过向量相似度查找相关内容。", "今天的午餐是米饭。"],
    "top_n": 1
  }'

import os
import uuid

import requests

documents = ["向量检索通过向量相似度查找相关内容。", "今天的午餐是米饭。"]
response = requests.post(
    "https://api.tokentosea.com/v1/rerank",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENTOSEA_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"model": "gte-rerank-v2", "query": "什么是向量检索？", "documents": documents, "top_n": 1},
    timeout=60,
)
response.raise_for_status()
for item in response.json()["output"]["results"]:  # 千问原生结构
    print(round(item["relevance_score"], 3), documents[item["index"]])

import { randomUUID } from 'node:crypto';

const documents = ['向量检索通过向量相似度查找相关内容。', '今天的午餐是米饭。'];
const response = await fetch('https://api.tokentosea.com/v1/rerank', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOKENTOSEA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID(),
  },
  body: JSON.stringify({ model: 'gte-rerank-v2', query: '什么是向量检索？', documents, top_n: 1 }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
for (const item of (await response.json()).output.results) { // 千问原生结构
  console.log(item.relevance_score.toFixed(3), documents[item.index]);
}

错误#

状态码	`code`	原因与处理
`422`	`endpoint_not_verified`	型号未开放本接口
`422`	`response_mode_not_verified`	本接口不支持流式
`400`	`main_wallet_authorization_failed`	输入过长，超出该型号单次预留上限
`4xx`	`provider_http_<状态码>`	厂商拒绝（例如文档数量超出厂商限制），未扣费

重排序POST

支持的型号#

请求体#

响应#

示例#

错误#

下一步#