> This page is for Model APIs.

> Sarvam Voice Agents (Samvaad) is a voice AI agent platform for Indian languages: build, test and deploy AI calling agents on your own phone numbers, from ₹3 a minute. Start here: https://docs.sarvam.ai/voice-agents/why-voice-agents.
> For clean Markdown of any page, append `.md` to the page URL.
> For a complete documentation index, see https://docs.sarvam.ai/llms.txt. For a section index, append `/llms.txt` to any section URL (for example https://docs.sarvam.ai/voice-agents/llms.txt).
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# EmbeddingGemma 2

> EmbeddingGemma 2 turns text into 768-dimension, unit-length vectors for search, retrieval, clustering, and classification, on the OpenAI-compatible POST /v2/embeddings. Available on Provisioned Throughput.

EmbeddingGemma 2 is an open-weight embedding model. It turns text into a **768-dimension vector
with length 1**, so the dot product of two vectors is their cosine similarity. Use it for semantic
search, retrieval for RAG, clustering, classification, and deduplication.

It is served on `POST /v2/embeddings`, which follows the OpenAI embeddings API, so the OpenAI SDKs
work with only the base URL changed.

> **Note**
>
> EmbeddingGemma 2 is available on **Provisioned Throughput**: capacity is set up for your workload and enabled for your organisation. Without access, requests return `404 not_found_error` and the model isn't listed in [`GET /v2/models`](/api-reference/chat/models-v2). [Contact us](/api/getting-started/help) to request access. See [Provisioned Throughput](/api/token-factory/models#provisioned-throughput).

## At a glance

|               |                                                                                                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Model ID**  | `embeddinggemma-2`                                                                                                           |
| **API**       | `POST https://api.sarvam.ai/v2/embeddings` (OpenAI-compatible)                                                               |
| **Input**     | Text: a string, or a list of strings in one request                                                                          |
| **Output**    | One 768-dimension, unit-length float vector per input, in input order                                                        |
| **Max input** | 8,192 tokens per string, checked against an estimate (in practice, about 6,500 English words). [Details](#known-limitations) |
| **Encodings** | `float` (default) or `base64`                                                                                                |
| **Pricing**   | ₹2 per 1M input tokens; no output tokens are billed ([Pricing](/api/getting-started/pricing))                                |

## Quickstart

Embed a query and a document, then compare them:

#### Python

```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_SARVAM_API_KEY",
    base_url="https://api.sarvam.ai/v2",
)

response = client.embeddings.create(
    model="embeddinggemma-2",
    input=[
        "task: search result | query: how do I reset my password",
        "title: none | text: To reset your password, open Settings > Security.",
    ],
)

query, document = (item.embedding for item in response.data)
similarity = sum(q * d for q, d in zip(query, document))
print(f"cosine similarity: {similarity:.3f}")
```

#### JavaScript

```javascript
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "YOUR_SARVAM_API_KEY",
    baseURL: "https://api.sarvam.ai/v2",
});

async function main() {
    const response = await client.embeddings.create({
        model: "embeddinggemma-2",
        input: [
            "task: search result | query: how do I reset my password",
            "title: none | text: To reset your password, open Settings > Security.",
        ],
    });

    const [query, document] = response.data.map((item) => item.embedding);
    const similarity = query.reduce((sum, q, i) => sum + q * document[i], 0);
    console.log(`cosine similarity: ${similarity.toFixed(3)}`);
}

main();
```

#### cURL

```bash
curl -X POST https://api.sarvam.ai/v2/embeddings \
  -H "api-subscription-key: $SARVAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embeddinggemma-2",
    "input": [
      "task: search result | query: how do I reset my password",
      "title: none | text: To reset your password, open Settings > Security."
    ]
  }'
```

Response (vectors shortened to their first values):

```json
{
  "object": "list",
  "model": "embeddinggemma-2",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.0061, 0.0338, 0.0432, ...]},
    {"object": "embedding", "index": 1, "embedding": [0.0139, 0.0393, 0.0321, ...]}
  ],
  "usage": {"prompt_tokens": 33, "total_tokens": 33, "completion_tokens": 0}
}
```

`data[i].index` matches the position of the string in `input`.

## Task prefixes

EmbeddingGemma 2 is trained with a prefix that says what each text is for. The API does not add
it, so put it at the start of every string. Without one, retrieval quality drops.

| Use                               | Prefix                                                  |
| --------------------------------- | ------------------------------------------------------- |
| Search or retrieval query         | `task: search result \| query: `                        |
| Document or passage being indexed | `title: none \| text: ` (or `title: {title} \| text: `) |
| Question answering                | `task: question answering \| query: `                   |
| Fact checking                     | `task: fact checking \| query: `                        |
| Classification                    | `task: classification \| query: `                       |
| Clustering                        | `task: clustering \| query: `                           |
| Semantic similarity               | `task: sentence similarity \| query: `                  |
| Code retrieval                    | `task: code retrieval \| query: `                       |

For search, embed queries with the query prefix and documents with the document prefix.

## Smaller vectors

`dimensions` is not supported and returns `400`. To store 512, 256, or 128 values per vector,
keep the first N values of the 768-dimension vector and scale it back to length 1:

```python
import math

def shorten(vector, n):
    head = vector[:n]
    norm = math.sqrt(sum(x * x for x in head))
    return [x / norm for x in head]
```

## Parameters

| Parameter         | Required | Description                                                                                         |
| ----------------- | -------: | --------------------------------------------------------------------------------------------------- |
| `model`           |      Yes | `embeddinggemma-2`.                                                                                 |
| `input`           |      Yes | A string, or a list of strings. Each string can be up to 8,192 tokens. An empty list returns `400`. |
| `encoding_format` |       No | `float` (default) or `base64`, a base64 string of 768 little-endian float32 values.                 |
| `dimensions`      |       No | Not supported; any value returns `400`. See [Smaller vectors](#smaller-vectors).                    |

## Known limitations

* Text only. Image embeddings are not available on the API.
* The task prefix is not added for you (see [Task prefixes](#task-prefixes)).
* Any string over 8,192 tokens fails the whole request. Split long documents into chunks before
  embedding them.
* The 8,192-token limit is checked against an **estimate** made before the text is tokenised, and the
  estimate runs high, at about 1.25 tokens per English word. A 7,000-word string (about 7,000 real tokens)
  is refused with "Estimated tokens (8750) exceed the context window of 8192". Keep each string under
  about 6,500 words.

## Limits and errors

| Area           | Limit or condition                                                                             | API response                                                                           | Recommended action                                                                |
| -------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Access         | Your organisation does not have Provisioned Throughput for this model                          | `404 not_found_error`; the model isn't listed in `GET /v2/models`                      | [Contact us](/api/getting-started/help) to request access.                        |
| Input length   | A string's estimated token count is over 8,192 (about 6,500 English words)                     | `400 invalid_request_error` ("Estimated tokens (…) exceed the context window of 8192") | Chunk the text.                                                                   |
| Empty input    | `input` is an empty list                                                                       | `400 invalid_request_error`                                                            | Send at least one string.                                                         |
| Dimensions     | `dimensions` is set                                                                            | `400 invalid_request_error`                                                            | Remove it and shorten vectors on your side.                                       |
| Endpoint       | `embeddinggemma-2` sent to another endpoint, or a non-embedding model sent to `/v2/embeddings` | `400 invalid_request_error` or `404 not_found_error`, naming the endpoint              | Send `embeddinggemma-2` to `POST /v2/embeddings` only.                            |
| Authentication | API key is missing or invalid                                                                  | `403 invalid_api_key_error`                                                            | Check the `api-subscription-key` header, or the API key passed to the OpenAI SDK. |
| Rate limit     | Request or concurrency limit is exceeded                                                       | `429 rate_limit_exceeded_error`                                                        | Back off and retry.                                                               |