Ranking
POST /v1/rerank orders your documents by how well each answers one question, with a score for
each and what it cost.
Request
Send it with an API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →, as JSON. The Rerank guide shows it at work. Souk Bot sends a customer's question and the passages of the shop's help pages; the answer lists the passages best first, each under its place in what you sent.
| Field | Needed | You send |
|---|---|---|
model | yes | a rerank model, lab/model. It also picks the meter: some models count searches, others tokens |
query | yes | the question the documents are ranked against |
documents | yes | one or more documents: each a string, or {"text": "...", "image": "..."} where the model reads pictures, the picture as a public link or a data:image/... address |
top_n | no | how many results come back, best first; absent, every document. Every document sent is scored either way |
provider | no | which providers may serve it: only and order name them, sort ranks them by price, throughput or latency, and max_price caps the price the router may pick, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → |
user | no | your own id for the person behind the request |
session_id | no | your own id grouping related requests, never sent to the model |
import json
import os
import urllib.request
API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/rerank"
MODEL = "cohere/rerank-4-pro"
documents = [
"A cancelled order refunds the deposit within 14 days.",
"Delivery outside Algiers takes three to five days.",
"Refunds return to the original payment method.",
]
request = urllib.request.Request(
ADDRESS,
data=json.dumps(
{
"model": MODEL,
"query": "Is the deposit refundable if I cancel?",
"documents": documents,
"top_n": 2,
}
).encode(),
headers={
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request) as response:
answer = json.load(response)
for result in answer["results"]:
print(result["relevance_score"], documents[result["index"]])
print(answer["usage"]["cost"])Response
200 OK, once every document is scored.
| Field | Holds |
|---|---|
id | the receipt handle, read back with GET /v1/generation |
model | the model that ranked them, lab/model |
provider | the provider that served it, when it is named |
results | the documents, best first: top_n entries, or one per document sent |
index | in each entry: the document's place in what you sent, from 0 |
relevance_score | in each entry: how well the document answers query; higher is better |
document | in each entry: the document as sent, its text, and its image where it carried one |
usage | what was counted, and the charge |
search_units | the searches counted, on a model that counts searches |
total_tokens | the tokens read, the query and the documents together |
cost | the charge, in DA |
Two headers ride the answer: X-Generation-Id, the receipt handle, and X-Balance-Available,
your balanceBalanceWhat you can spend, in DA.More on Balance and charges → after this charge, in µDAµDAA millionth of a DA: 1 DA = 1 000 000 µDA.More on Balance and charges →.
What it cost
Charged in DA from your balance the moment the answer ends, on the model's own meter: its
searches, usage.search_units, or its tokens, usage.total_tokens. Both counters ride every
answer; the model's page shows which one it charges and at what rate. usage.cost carries the
charge.
- Picks the price:
model, which also picks the meter. - Moves the count:
queryanddocuments. On a model that counts searches, a long document is cut into pieces first and each piece counts toward the documents one search covers, so long documents can take more than one search. - Changes the answer, never the bill:
top_n. Every document sent is scored and counted, however few results come back.
Nothing that comes back is counted. Nothing is charged when the provider fails before it answers. An answer with no result still charges the documents that were scored.
Errors
The body says why.
| Status | When |
|---|---|
| 400 | model, query or documents is missing, documents is empty, a document is neither a string nor an object, or a field has the wrong type |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; error.metadata.limit_source names which, and deposit_url or key_url says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries Retry-After: 60 |
| 403 | the key is kept to other models or other addresses, a guardrail's budget is spent, or a guardrail or a filter blocked the request |
| 404 | model is not a rerank model on sale, or no provider serves it |
| 502 | the provider failed, or answered with nothing usable |
Last modified on