> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideren.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeddings.

> Vectors for retrieval and agent memory, next to your chat calls — same key, same origin. Seven models from 384 to 2048 dimensions, OpenAI-compatible.

## Endpoint

```http theme={null}
POST /v1/embeddings
```

Authenticate with `Authorization: Bearer sdn_...`. Pass any model from the table below as
`model`; it defaults to the `@sdn/bge-base-en` row (the alias `sdn-embed` still works).
Embeddings are included on every paid plan.

The table lists each model under its public id, as `GET /v1/models` does. The older
spellings — `sdn-bge-m3` and the bare `bge-m3` — resolve too.

Embedding requests are never re-routed. The model you name is the model that runs — we
never substitute a different one, because vectors from a different model cannot be
compared against an index you have already built. If the model can't be served, you get an
error, never a vector from another model.

| Model | Dimensions | Max input | Notes |
| - | - | - | - |
| `@sdn/bge-small-en` | 384 | 512 tokens | 384 dimensions — the smallest index and the fastest search. |
| `@sdn/bge-base-en` | 768 | 512 tokens | The long-standing default English embedding. |
| `@sdn/embed-gemma-300m` | 768 | 2,048 tokens | Compact Gemma-family embedding with a 2K input window. |
| `@sdn/bge-large-en` | 1024 | 512 tokens | The most accurate English embedding in the catalog. |
| `@sdn/bge-m3` | 1024 | 8,192 tokens | BAAI's versatile embedding — multilingual, multi-granularity. |
| `@sdn/qwen3-embed-0.6b` | 1024 | 8,192 tokens | Multilingual retrieval with an 8K input window. |
| `@sdn/plamo-embed-1b` | 2048 | 4,096 tokens | Japanese-specialist embedding — the widest vector in the catalog. |

## Request parameters

| Parameter | Type | Notes |
| - | - | - |
| `model` | string | Any id from the table above. Defaults to the `@sdn/bge-base-en` row (alias `sdn-embed`). An unknown id returns `404` — never a substitute. |
| `input` | string \| string\[] · required | One text or a batch — up to 2,048 items per request. Token arrays are not supported. |
| `encoding_format` | string | `float` (default) or `base64`. |
| `dimensions` | integer | Optional; if set it must equal the chosen model's own width — each model has one fixed output size. |

## Example

<CodeGroup>
  ```sh curl theme={null}
  curl https://api.sideren.io/v1/embeddings \
    -H "authorization: Bearer $SIDEREN_API_KEY" \
    -H "content-type: application/json" \
    -d '{
      "model": "@sdn/bge-base-en",
      "input": ["agent memory entry one", "agent memory entry two"]
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.sideren.io/v1",
      api_key="sdn_your_key",
  )

  r = client.embeddings.create(
      model="@sdn/bge-base-en",
      input=["agent memory entry one", "agent memory entry two"],
  )
  print(len(r.data[0].embedding))  # 768
  ```

  ```ts TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.sideren.io/v1",
    apiKey: process.env.SIDEREN_API_KEY,
  });

  const r = await client.embeddings.create({
    model: "@sdn/bge-base-en",
    input: ["agent memory entry one", "agent memory entry two"],
  });
  console.log(r.data[0].embedding.length); // 768
  ```
</CodeGroup>

```json title="Response (shape)" theme={null}
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.013, -0.021, ...] },
    { "object": "embedding", "index": 1, "embedding": [0.007,  0.049, ...] }
  ],
  "model": "@sdn/bge-base-en",
  "usage": { "prompt_tokens": 12, "total_tokens": 12 }
}
```

<Note>
  Vectors come back in input order — `index` matches the position of each text in
  `input`. Cosine similarity is the intended distance measure.
</Note>

## Errors

Empty input, more than 2,048 items, or a `dimensions` value that does not match the model
return `400` with an OpenAI-shaped body. An unrecognised `model` returns `404`. On the
free plan, embeddings return `400` `plan_upgrade_required`; the message names the cheapest
plan that includes the model. Full reference:
[Errors](/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.