# Embeddings & rerank

> Generate text embeddings with /v1/embeddings, re-score retrieval candidates with /v1/rerank, and combine both into a RAG pipeline.

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 [catalogue](/docs/models).
:::

Browse models in the [catalogue](/docs/models) or with `GET /v1/models`; the `output_modalities` field reports each model's output type. The `vendor/` prefix shown in the console is for browsing and filtering only — it is not part of an API request id.

## Embeddings

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

### Request

```python
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))
```

```bash
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 — it never includes amounts. Reconcile spend in the console, `GET /api/usage/token` (summary), or `GET /api/log/token` (per request).

### Request parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | Embedding model id from the catalogue. 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

The same functionality is available at `POST /v1/engines/{model}/embeddings`, where the model id moves into the URL path. Authenticate with `x-goog-api-key` (or `?key=`).

```bash
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. It is exposed through a single OpenAI-compatible endpoint.

### Request

```python
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"))
```

```bash
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 console, `GET /api/usage/token`, or `GET /api/log/token`.

### Request parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | Rerank model id from the catalogue. 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](/docs/tutorials/rag) 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: insufficient balance, model whitelist, quota, or IP allowlist. Insufficient balance 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](/docs/tutorials/rag) — the full pipeline in one runnable file.
- [Models](/docs/models) — browse embedding and rerank models.
- [Errors](/docs/api-reference/errors) — status codes and the error envelope.
- [Authentication](/docs/api-reference/authentication) — API key auth per protocol.