rerank-2.5 is Voyage AI's instruction-following reranker, designed to refine a set of search candidates. It jointly examines the query and each document as a cross-encoder, then returns a relevance ordering. The maker's release emphasizes natural-language control over what counts as relevant, multilingual retrieval and a longer query–document context than the preceding rerank-2 edition.
The input is a query and a list of candidate text documents. These can be passages selected by embedding search or a lexical first-stage search. The reranker evaluates the supplied text rather than creating corpus embeddings, so its practical job is to refine the candidates the initial search already found.
Keep the original candidate ordering and source identifiers when preparing that list. The returned indices refer to those input positions. For a RAG task, supply the passages the answer stage might actually use, including the title or qualifications needed to interpret them. A relevant document that is absent from the submitted candidate set cannot appear as a newly found result of reranking.
Instructions can be appended or prepended to the query. The release describes three useful roles: emphasize a particular part of a document, prefer a type of source and disambiguate the query with application context. These alter the relevance task presented to the model.
For a technical search, an illustrative instruction is “Prioritize passages that explain the failure and recovery behavior; introductory overviews are secondary.” For a research collection, specify whether the title, method or result matters most. For an ambiguous term, state the subject area the search is about. Keep the question and the instruction compatible, so one does not ask for a broad topic while the other silently changes the task.
These preferences guide relevance scoring. If the application has strict eligibility requirements—such as source version, date or access scope—prepare the eligible candidate set separately. The model's relevance instruction and a deterministic collection restriction serve different purposes.
Results are ordered by descending relevance and include a floating-point relevance score and the candidate's original input index. The top-k option selects how many leading results to return; without it, the manufacturer specification returns results for all submitted candidates. An optional return-documents setting includes the corresponding source text; otherwise the response contains indices and scores.
Use the ordering to select passages for display or a later answer stage, keeping their source identity intact. Inspect the actual text when evaluating the ranking: the score is a measure of relevance to the submitted query, not a generated answer or a verification that the document's claims are correct. This makes the model useful for refining technical, legal, financial, medical, conversation and multilingual search material without converting ranking into a domain conclusion.
The documented query limit is 8,000 tokens, including instructions placed in the query. The query plus any one candidate document must fit within 32,000 tokens, and the document list can contain at most 1,000 items. The total allowance is 600,000 tokens, counted as query tokens multiplied by the number of documents, plus all document tokens. A long instruction is therefore counted repeatedly across the candidate pairs.
The output top-k count does not change the number of candidates in that input-token calculation. Default truncation shortens over-length queries or documents to meet the context limit; disabling it makes an over-length query or pair return an error. Prepare answer-bearing passages deliberately and keep the relevant qualification within the text the model will see. Evaluate the refined order on representative questions and instructions, then pass the selected original passages to the next stage.
", "aboutText": "rerank-2.5 is Voyage AI's instruction-following reranker, designed to refine a set of search candidates. It jointly examines the query and each document as a cross-encoder, then returns a relevance ordering. The maker's release emphasizes natural-language control over what counts as relevant, multilingual retrieval and a longer query–document context than the preceding rerank-2 edition.\n\n### Give the model the candidates to compare\n\nThe input is a query and a list of candidate text documents. These can be passages selected by embedding search or a lexical first-stage search. The reranker evaluates the supplied text rather than creating corpus embeddings, so its practical job is to refine the candidates the initial search already found.\n\nKeep the original candidate ordering and source identifiers when preparing that list. The returned indices refer to those input positions. For a RAG task, supply the passages the answer stage might actually use, including the title or qualifications needed to interpret them. A relevant document that is absent from the submitted candidate set cannot appear as a newly found result of reranking.\n\n### Specify the intended notion of relevance\n\nInstructions can be appended or prepended to the query. The release describes three useful roles: emphasize a particular part of a document, prefer a type of source and disambiguate the query with application context. These alter the relevance task presented to the model.\n\nFor a technical search, an illustrative instruction is “Prioritize passages that explain the failure and recovery behavior; introductory overviews are secondary.” For a research collection, specify whether the title, method or result matters most. For an ambiguous term, state the subject area the search is about. Keep the question and the instruction compatible, so one does not ask for a broad topic while the other silently changes the task.\n\nThese preferences guide relevance scoring. If the application has strict eligibility requirements—such as source version, date or access scope—prepare the eligible candidate set separately. The model's relevance instruction and a deterministic collection restriction serve different purposes.\n\n### Ranked output and later result use\n\nResults are ordered by descending relevance and include a floating-point relevance score and the candidate's original input index. The top-k option selects how many leading results to return; without it, the manufacturer specification returns results for all submitted candidates. An optional return-documents setting includes the corresponding source text; otherwise the response contains indices and scores.\n\nUse the ordering to select passages for display or a later answer stage, keeping their source identity intact. Inspect the actual text when evaluating the ranking: the score is a measure of relevance to the submitted query, not a generated answer or a verification that the document's claims are correct. This makes the model useful for refining technical, legal, financial, medical, conversation and multilingual search material without converting ranking into a domain conclusion.\n\n### Context, total-token budget and truncation\n\nThe documented query limit is 8,000 tokens, including instructions placed in the query. The query plus any one candidate document must fit within 32,000 tokens, and the document list can contain at most 1,000 items. The total allowance is 600,000 tokens, counted as query tokens multiplied by the number of documents, plus all document tokens. A long instruction is therefore counted repeatedly across the candidate pairs.\n\nThe output top-k count does not change the number of candidates in that input-token calculation. Default truncation shortens over-length queries or documents to meet the context limit; disabling it makes an over-length query or pair return an error. Prepare answer-bearing passages deliberately and keep the relevant qualification within the text the model will see. Evaluate the refined order on representative questions and instructions, then pass the selected original passages to the next stage.", "editorialOverlay": { "copy_fields": null, "copy_sha256": null, "copy_source": null, "html_sha256": "d74d92275acdd3db2f792a53acdd436494d7489c3337ccc63c5a4dbeee4a7983", "module_sha256": "ee9dc1c50b1e6a8fb7fa062030fcb4646b9aaaeb08be513b723a5a92a7290f06", "raw_model_unchanged": true, "schema": "ailoot-native-model-editorial-v1" }, "locale": "en", "methods": [ { "html": "voyageai/rerank-2.5rerank-2.5 reorders a supplied set of text candidates by relevance to a query and optional natural-language instructions. It is a multilingual, quality-oriented reranker with a 32,000-token query–document context and ranked scores tied to the original candidate indices.
This description covers the model’s capabilities. Available in Ailoot inputs, outputs and options are listed for the selected method below.
rerank-2.5 is Voyage AI's instruction-following reranker, designed to refine a set of search candidates. It jointly examines the query and each document as a cross-encoder, then returns a relevance ordering. The maker's release emphasizes natural-language control over what counts as relevant, multilingual retrieval and a longer query–document context than the preceding rerank-2 edition.
The input is a query and a list of candidate text documents. These can be passages selected by embedding search or a lexical first-stage search. The reranker evaluates the supplied text rather than creating corpus embeddings, so its practical job is to refine the candidates the initial search already found.
Keep the original candidate ordering and source identifiers when preparing that list. The returned indices refer to those input positions. For a RAG task, supply the passages the answer stage might actually use, including the title or qualifications needed to interpret them. A relevant document that is absent from the submitted candidate set cannot appear as a newly found result of reranking.
Instructions can be appended or prepended to the query. The release describes three useful roles: emphasize a particular part of a document, prefer a type of source and disambiguate the query with application context. These alter the relevance task presented to the model.
For a technical search, an illustrative instruction is “Prioritize passages that explain the failure and recovery behavior; introductory overviews are secondary.” For a research collection, specify whether the title, method or result matters most. For an ambiguous term, state the subject area the search is about. Keep the question and the instruction compatible, so one does not ask for a broad topic while the other silently changes the task.
These preferences guide relevance scoring. If the application has strict eligibility requirements—such as source version, date or access scope—prepare the eligible candidate set separately. The model's relevance instruction and a deterministic collection restriction serve different purposes.
Results are ordered by descending relevance and include a floating-point relevance score and the candidate's original input index. The top-k option selects how many leading results to return; without it, the manufacturer specification returns results for all submitted candidates. An optional return-documents setting includes the corresponding source text; otherwise the response contains indices and scores.
Use the ordering to select passages for display or a later answer stage, keeping their source identity intact. Inspect the actual text when evaluating the ranking: the score is a measure of relevance to the submitted query, not a generated answer or a verification that the document's claims are correct. This makes the model useful for refining technical, legal, financial, medical, conversation and multilingual search material without converting ranking into a domain conclusion.
The documented query limit is 8,000 tokens, including instructions placed in the query. The query plus any one candidate document must fit within 32,000 tokens, and the document list can contain at most 1,000 items. The total allowance is 600,000 tokens, counted as query tokens multiplied by the number of documents, plus all document tokens. A long instruction is therefore counted repeatedly across the candidate pairs.
The output top-k count does not change the number of candidates in that input-token calculation. Default truncation shortens over-length queries or documents to meet the context limit; disabling it makes an over-length query or pair return an error. Prepare answer-bearing passages deliberately and keep the relevant qualification within the text the model will see. Evaluate the refined order on representative questions and instructions, then pass the selected original passages to the next stage.
POST /v1/reranktextrerank| Field | Type | Requirement | Values & limits | Default |
|---|---|---|---|---|
Fielddocuments | Typearray | RequirementRequired | Values & limits | Default— |
Fieldmodel | Typestring | RequirementRequired | Values & limits voyageai/rerank-2.5 | Default— |
Fieldprovider | Typeschema | RequirementOptional | Values & limits | Default— |
Fieldquery | Typestring | RequirementRequired | Values & limits | Default— |
Fieldsession_id | Typestring | RequirementOptional | Values & limits | Default— |
Fieldtop_n | Typeinteger | RequirementOptional | Values & limits Minimum: 1 | Default— |
Fieldtrace | Typeschema | RequirementOptional | Values & limits | Default— |
Fielduser | Typestring | RequirementOptional | Values & limits | Default— |
Fielddocuments[].text | Typestring | RequirementOptional | Values & limits | Default— |
Fielddocuments[].image | Typestring | RequirementOptional | Values & limits | Default— |
text_rerank · Required: query, documents array with minItems1
| Parameter | Contract |
|---|---|
Parametercontent_type | Contractapplication/json |
Parameterrequired | Contractmodel, query, documents |
Parametermaterial_types | Contracttext |
Parameteroptional_controls | Contractprovider, session_id, top_n, trace, user |
Parametermultimodal_input_binding | Contractnull |
Lifecycle: synchronous
Send the exact model ID and retain the complete native response.
Tariff references do not add request options. Supported parameters are listed for the selected method.
Match each charge to the conditions shown. Use one rate for each set of alternative configurations.
| Configuration | Rate schedule | Billing unit | Charge |
|---|---|---|---|
| ConfigurationBase token rates | Rate scheduleBase rate | Billing unit— | Charge Input · Input tokens — / 1K tokens Output · Output tokens — / 1K tokens Input · Cache read — / 1K tokens Input · Cache write — / 1K tokens Input · Cache write, 1 hour — / 1K tokens |
| ConfigurationUltra | Rate schedule— | Billing unit/ 1K tokens | Charge Input · input token $0.0001 / 1K tokens |
Ailoot reserves an estimated amount before a request. After the result, it settles the final charge from measured usage. Streaming settlement uses the final usage record. How reservation and settlement work →
{\n "documents": [\n "Paris is the capital of France.",\n "Berlin is the capital of Germany."\n ],\n "model": "voyageai/rerank-2.5",\n "query": "What is the capital of France?",\n "top_n": 3\n}set -eu\n: "${AILOOT_API_KEY:?Set your Ailoot API key}"\n: "${AILOOT_REQUEST_FILE:?Set your actual JSON request file}"\nexport AILOOT_REQUEST_FILE\npython3 - <<'PY_REQUEST'\nimport json,os\nfrom pathlib import Path\np=json.loads(Path(os.environ['AILOOT_REQUEST_FILE']).read_text(encoding='utf-8'))\nif not isinstance(p,dict): raise SystemExit('Request must be a JSON object')\np['model']='voyageai/rerank-2.5'\nPath('request.json').write_text(json.dumps(p,ensure_ascii=False),encoding='utf-8')\nPY_REQUEST\ncurl --fail-with-body --silent --show-error https://api.ailoot.ai/v1/rerank \\\n -H "Authorization: Bearer $AILOOT_API_KEY" -H 'Content-Type: application/json' \\\n --data-binary @request.json -D response-headers.txt -o result.json\npython3 - <<'PY_RESULT'\nimport json\nfrom pathlib import Path\nprint(json.dumps(json.loads(Path('result.json').read_text()),ensure_ascii=False,indent=2))\nPY_RESULT\njson
Keep every complete returned response, file and content part.
Every actual result index, finite relevance_score and original document object is retained. Indices bind the original document array. Entire original JSON is stored and returned only after settlement.
Preserve original operation and full/partial reply; do not replay POST.
| Field | Type |
|---|---|
Fieldmodel | Typestring |
Fieldid | Typestring |
Fieldprovider | Typestring |
Fieldresults[].index | Typeinteger |
Fieldresults[].relevance_score | Typenumber |
Fieldresults[].document.text | Typestring |
Fieldresults[].document.image | Typestring |
Fieldusage.search_units | Typeinteger |
Fieldusage.total_tokens | Typeinteger |
Fieldusage.cost | Typenumber |
| Response | Condition | Next step |
|---|---|---|
Response400 · invalid_request_error | ConditionInvalid required field, representation or value | Next stepCorrect the indicated request field. |
Ailoot Ultra voyageai/rerank-2.5
Use the method paths shown above.