The second pass that fixes retrieval

The call

curl https://freemodel.online/v1/rerank \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/rerank",
    "query": "how do I rotate an API key?",
    "documents": [
      "Keys can be rotated from the console.",
      "Billing is metered per request.",
      "Rotating a key invalidates the old one immediately."
    ],
    "top_n": 2
  }'

{
  "results": [
    { "index": 2, "relevance_score": 0.93 },
    { "index": 0, "relevance_score": 0.71 }
  ],
  "usage": { … }
}

index refers to the position in your documents array — the API does not echo the text back unless you ask for it. Pass return_documents: true and each result gains a document field.

Where this fits

The usual shape of a retrieval pipeline is two stages. First a fast approximate search — embeddings, an index, a top_k that is deliberately generous, because recall matters more than precision at this step. Then a slower, more accurate pass over those candidates.

auto/rerank is the second stage. It is worth adding when your top_k is larger than what you actually feed the model — which is most of the time, because the good answer is usually somewhere in the top twenty and rarely at position one.

It pairs with the embedding alias: embed once, store the vectors, then rerank at query time.

Request fields

One model sits behind the alias. A reranking model swap reorders your results without telling you — the same query returns a different ranking, and nothing in the response looks unusual. Failing is the safer behaviour.

Related capabilities

Same naming scheme, one alias per capability — all listed in /v1/models:

Sources

Every third-party figure quoted on this site was read from the vendor documentation linked below, on the date stated. None of these links are affiliate links and none of these vendors paid to be listed. If a number here disagrees with the page it came from, the page is right — tell us and it gets corrected.

• OpenRouter — credit-purchase fees and free-model rate limits
• OpenRouter — rate-limit reference
• OpenRouter — public model list
• LiteLLM — licence, deployment options and supported models
• Cloudflare AI Gateway — features and pricing
• Vercel AI Gateway — features
• Portkey — plans
• Helicone — plans
• Model Context Protocol — specification
• OpenAI Python SDK — base_url and OPENAI_BASE_URL
• Anthropic Messages API — request format

What this is

auto/rerank scores candidate documents against a query and returns them sorted, behind POST /v1/rerank, in the response shape existing rerank clients already parse.

Key numbers

• 5 个请求字段
• 3 个必填字段
• 1 个固定模型
• 5 request fields: model, query, documents required; top_n, return_documents optional.
• index is the position in your own documents array, not the rank — 2 means the third document you sent.
• 1 model behind the alias; 0 silent swaps, because a different reranker reorders the same query.

How to use it, step by step

1. Step 1. Recall: embed with auto/embed, index the vectors, and take a generous top_k.
2. Step 2. Rerank: POST the query and those candidates to /v1/rerank with top_n.
3. Step 3. Assemble: map the returned index values back to your array; add return_documents: true if you want the text echoed.

A two-stage retrieval vs embeddings alone: recall first, then rerank — the second stage is what fixes the order.

FAQ

What does the returned index mean?

It is the position in the array you sent. The API returns scores and positions, not text, unless you ask for documents.

Will the model behind the alias change?

No. It changes only if the current model is retired upstream — a silent swap would change the order of the same query with no error.

When is reranking worth the extra call?

Whenever your top_k is larger than what you feed the model — which is almost always. The right document is usually in the top 20 but rarely at rank 1.

When to use it — and when not to

Use it after retrieval: take the top 20–50 candidates from a vector or keyword search and rerank them so the best 5 reach the model. It improves precision without re-indexing the corpus.

Do not use it as a replacement for retrieval. Reranking cannot surface a document that was never in the candidate set, and it adds latency to every query.

Limits worth designing around

• Candidate count: reranking 50 items is cheap; reranking 500 is not. Retrieve wide, rerank narrow.
• Score interpretation: scores are comparable within one query, not across queries. Use them for ordering, not as absolute relevance.
• Latency budget: reranking sits on the critical path. Measure p95 with your real candidate count before shipping.
• One model per alias: changing the reranker changes the ordering; keep an eval set to catch regressions.
• Text length: long candidates get truncated. Keep the title and the most relevant paragraph, not the whole document.

Cost and latency

Reranking is priced per request or per token pair and is usually much cheaper than generation. The real cost is latency: every query pays it. Cache reranked results for repeated queries and skip reranking when the first-stage score gap is already large.

Measure the lift on a fixed eval set: recall@5 before and after reranking. If the lift is under a few points, the added latency may not be worth it.

Two more questions

Should I rerank every query? No. Rerank when the first-stage results are close in score or when the query is ambiguous; skip it for exact-match lookups.

Can I combine rerank scores with vector scores? Yes, but normalize first and test the blend on your eval set. A naive sum of two differently scaled scores usually performs worse than either alone.