Embeddings & Reranking
The two halves of a retrieval pipeline. Embeddings find candidates cheaply across a large corpus; reranking puts the right one at the top of the short list that comes back.
Embeddings
POST /api/v1/embeddings, in the OpenAI shape. Pass a string or an array of strings.
import openai
client = openai.OpenAI(
api_key="your-api-key",
base_url="https://mume.ai/api/v1",
)
result = client.embeddings.create(
model="openai/text-embedding-3-small",
input=["the migration never turned the old path off",
"shipping is flat until the free threshold"],
)
print(len(result.data), len(result.data[0].embedding))curl https://mume.ai/api/v1/embeddings \
-H "Authorization: Bearer $MUME_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/text-embedding-3-small",
"input": "the migration never turned the old path off"
}'Response
{
"object": "list",
"data": [
{ "object": "embedding", "index": 0, "embedding": [0.0023, -0.0117, "…"] }
],
"model": "openai/text-embedding-3-small",
"usage": { "prompt_tokens": 9, "total_tokens": 9, "cost": 0.0000002 }
}model and a non-empty input are required. Everything else is passed through to the provider, so a parameter the model supports — dimensions, for instance — works here too.
Reranking
POST /api/v1/rerank takes a query and a list of documents and returns them scored. This is the step people most often skip and most often need: a vector search over a large corpus is optimised for recall, and the ordering it produces within the top fifty is frequently wrong.
curl https://mume.ai/api/v1/rerank \
-H "Authorization: Bearer $MUME_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "cohere/rerank-v3.5",
"query": "how do I rotate an API key",
"documents": [
"Keys are created from the dashboard under Keys.",
"Revoking a key takes effect immediately; create the replacement first.",
"Billing is pay-as-you-go and credit lasts a year."
],
"top_n": 2
}'Response
{
"id": "rr_01H…",
"results": [
{ "index": 1, "relevance_score": 0.94 },
{ "index": 0, "relevance_score": 0.61 }
],
"usage": { "cost": 0.000021, "search_units": 1 }
}model, query and a non-empty documents array are required. Results carry the index into the array you sent rather than the document text, so keep your originals and look them up.
Cost
Both endpoints report usage.cost in USD and bill at 1:1 pass-through, the same as everything else on the gateway. Neither produces an asset, so unlike images or speech there is nothing stored and nothing to fetch afterwards — the response is the whole result.
Putting them together
- Embed your corpus once, and store the vectors wherever you keep them.
- Embed the query and take the nearest fifty or so.
- Rerank those fifty against the query and use the top three or four.
The second step is cheap and approximate; the third is precise and only pays for what survived the second. Doing the third over the whole corpus is the mistake this split exists to avoid.
Related
- Moderation — the third plain-JSON endpoint, billed the same way.
- Web Search — retrieval you do not have to build a corpus for.