opendunes
Embeddings, rerank, classification
Copy page ▾

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.

FieldNeededYou send
modelyesa rerank model, lab/model. It also picks the meter: some models count searches, others tokens
queryyesthe question the documents are ranked against
documentsyesone 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_nnohow many results come back, best first; absent, every document. Every document sent is scored either way
providernowhich 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 →
usernoyour own id for the person behind the request
session_idnoyour 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.

FieldHolds
idthe receipt handle, read back with GET /v1/generation
modelthe model that ranked them, lab/model
providerthe provider that served it, when it is named
resultsthe documents, best first: top_n entries, or one per document sent
indexin each entry: the document's place in what you sent, from 0
relevance_scorein each entry: how well the document answers query; higher is better
documentin each entry: the document as sent, its text, and its image where it carried one
usagewhat was counted, and the charge
search_unitsthe searches counted, on a model that counts searches
total_tokensthe tokens read, the query and the documents together
costthe 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: query and documents. 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.

StatusWhen
400model, query or documents is missing, documents is empty, a document is neither a string nor an object, or a field has the wrong type
401the key is missing, wrong, disabled or expired
402your 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
403the key is kept to other models or other addresses, a guardrail's budget is spent, or a guardrail or a filter blocked the request
404model is not a rerank model on sale, or no provider serves it
502the provider failed, or answered with nothing usable

Last modified on