Embeddings & rerank

Embeddings and reranking are the two retrieval building blocks of a RAG pipeline. Embeddings turn text into vectors for fast, approximate recall; reranking re-scores a short list of candidates against the query with a cross-encoder for precision.

Note

Pick the right model. Embedding and rerank endpoints need dedicated model types; a chat model will not work. Replace deepseek-chat in the examples below with an embedding (or rerank) model from the catalog.

Browse models in the catalog or with GET /v1/models. The output_modalities field reports each model’s output type. The vendor/ prefix shown in the Platform is for browsing and filtering only; it is not part of the model ID you send to the API.

Embeddings

POST /v1/embeddings turns text into vectors. Pass one string or a batch of strings and get back one embedding per item.

Request

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.mirapi.ai/v1", api_key=os.environ["MIRAPI_API_KEY"])

response = client.embeddings.create(
    model="deepseek-chat",
    input=["MirAPI is a unified API gateway", "Embeddings capture meaning"],
)

for item in response.data:
    print(item.index, len(item.embedding))

curl https://api.mirapi.ai/v1/embeddings \
  -H "Authorization: Bearer $MIRAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek-chat",
  "input": ["Embeddings capture meaning"]
  }'

The response contains data[] (each entry has index and embedding), model, and usage (prompt_tokens, total_tokens). usage reports token counts only and never includes cost. Reconcile spend in the Platform, GET /api/usage/token (account-level summary), or GET /api/log/token (per-request detail).

Request parameters

Parameter	Type	Description
model	string	Embedding model ID from the catalog. Required.
input	string | string[]	Text to embed: a single string or an array of strings. Required.
encoding_format	string	float (default) or base64.
dimensions	integer	Output vector length, for models that support dimension control.

Gemini-style endpoint

Embeddings are also available at POST /v1/engines/{model}/embeddings, with the model ID in the URL path. Authenticate with x-goog-api-key (or ?key=).

curl "https://api.mirapi.ai/v1/engines/deepseek-chat/embeddings" \
  -H "x-goog-api-key: $MIRAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": ["Embeddings capture meaning"],
  "encoding_format": "float"
  }'

Rerank

POST /v1/rerank re-scores documents against a query. This OpenAI-compatible endpoint is the only rerank route.

Request

import os
import requests

response = requests.post(
    "https://api.mirapi.ai/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['MIRAPI_API_KEY']}"},
    json={
        "model": "deepseek-chat",
        "query": "How do I ground LLM answers in my own documents?",
        "documents": [
            "RAG grounds answers in external data.",
            "Vectors measure semantic similarity.",
            "Cross-encoders compare query and document directly.",
        ],
        "top_n": 2,
        "return_documents": True,
    },
)

for result in response.json()["results"]:
    print(result["relevance_score"], result.get("document", {}).get("text"))

curl https://api.mirapi.ai/v1/rerank \
  -H "Authorization: Bearer $MIRAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek-chat",
  "query": "How do I ground LLM answers in my own documents?",
  "documents": [
    "RAG grounds answers in external data.",
    "Vectors measure semantic similarity.",
    "Cross-encoders compare query and document directly."
  ],
  "top_n": 2,
  "return_documents": true
  }'

Results are sorted by relevance_score (highest first). Each entry carries index and relevance_score; when return_documents is true, document.text is also included. The response has no usage field, so reconcile spend in the Platform, GET /api/usage/token, or GET /api/log/token.

Request parameters

Parameter	Type	Description
model	string	Rerank model ID from the catalog. Required.
query	string	The query text to score against. Required.
documents	string[]	Documents to re-score. Required.
top_n	integer	Return only the top N results.
return_documents	boolean	Include each document’s text in the response. Default false.

Their roles in RAG

1. Index: chunk your documents, embed every chunk, and store the vectors.
2. Recall: embed the query and find the top N (for example 20) nearest chunks.
3. Rerank: send those 20 candidates to /v1/rerank and keep the best 3.
4. Generate: put the top chunks in the prompt and let the chat model answer with citations.

The RAG tutorial implements this whole pipeline in one runnable file.

Error handling

• 401: the key is missing, invalid, or unknown. Check the auth header.
• 403: the key is valid but the request was rejected by the model whitelist, quota, or IP allowlist. Insufficient balance also returns 403.
• 413: the input is too large. Send fewer items per request.
• 429: rate limited. Retry with exponential backoff and jitter (1s → 2s → 4s, capped around 30s). There is no Retry-After header.
• 500: a server-side failure. Idempotent requests can be retried safely.

The gateway does not retry for you. OpenAI-format errors use the {"error": {"message", "type", "param", "code"}} envelope, and every error message ends with a request ID. Include it when you open a ticket.

Related links

• RAG tutorial: the full pipeline in one runnable file.
• Models: browse embedding and rerank models.
• Errors: status codes and the error envelope.
• Authentication: API key auth per protocol.