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

# Embeddings

> POST /v1/embeddings. Generate vector embeddings for semantic search, retrieval, and RAG.

`POST /v1/embeddings`

Creates embedding vectors for one or more strings. OpenAI-compatible: any OpenAI SDK, LangChain, LlamaIndex, or LiteLLM configuration works by pointing its base URL at the gateway.

Embedding models use the same `model:level` naming as every other model (for example `titan-embed-text-v2:il5`), so your text is processed on infrastructure authorized at the level you request.

## Request

### Headers

| Header         | Required | Description        |
| -------------- | -------- | ------------------ |
| `x-api-key`    | Yes      | Your API key       |
| `Content-Type` | Yes      | `application/json` |

### Body Parameters

| Parameter         | Type                       | Required | Description                                                                                          |
| ----------------- | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `model`           | string                     | Yes      | An embedding model ID (see [Models](/models))                                                        |
| `input`           | string or array of strings | Yes      | Text to embed. Up to 512 strings per request, 2 MB total. Token arrays are not accepted.             |
| `encoding_format` | string                     | No       | `float` (default) or `base64`. The OpenAI SDKs request `base64` automatically and decode it for you. |

Unrecognized fields (such as `user` or `dimensions`) are ignored. Vector size is fixed per model.

### Example

```bash theme={null}
curl https://api.consus.io/v1/embeddings \
  -H "x-api-key: $CONSUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "titan-embed-text-v2:il5",
    "input": ["first document chunk", "second document chunk"]
  }'
```

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

client = OpenAI(base_url="https://api.consus.io/v1", api_key=CONSUS_API_KEY)
result = client.embeddings.create(
    model="titan-embed-text-v2:il5",
    input=["first document chunk", "second document chunk"],
)
vectors = [d.embedding for d in result.data]
```

## Response

```json theme={null}
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, ...] },
    { "object": "embedding", "index": 1, "embedding": [0.0789, 0.0012, ...] }
  ],
  "model": "titan-embed-text-v2:il5",
  "usage": { "prompt_tokens": 9, "total_tokens": 9 }
}
```

`data[i]` corresponds to `input[i]`. With `encoding_format: "base64"`, `embedding` is a base64 string of little-endian float32 values.

## Models

| Model                 | Vector size | Max input    | Notes                                                                          |
| --------------------- | ----------- | ------------ | ------------------------------------------------------------------------------ |
| `titan-embed-text-v2` | 1024        | 8,192 tokens | Unit-normalized. Text only. Available at `:fedramp-high`, `:il5`, and `:itar`. |

Vector size is fixed per model so that an index you build today stays valid.

## Behavior and Limits

* **Batching.** Up to 512 strings per request; larger batches are rejected with a `400` rather than truncated, so split them client-side. Each string in `input` is embedded as its own upstream call; a request with many strings takes correspondingly longer. Large ingestion jobs may see `429` responses when the upstream per-minute quota is reached — standard client retry with backoff handles this.
* **Over-length input** returns `400`; text is never silently truncated.
* **Billing** is per input token at the model's rate. There are no output tokens.
* **Nothing is stored.** Inputs and vectors are returned to you and discarded, the same zero-persistence posture as every other endpoint.
* Embedding models are rejected on `/v1/chat/completions`, `/v1/messages`, and `/v1/responses`, and chat models are rejected here, each with a `400` that names the correct endpoint.
* There is no Anthropic-SDK equivalent of this endpoint; use an OpenAI-compatible client for embeddings even if the rest of your application uses `/v1/messages`.

## Errors

See [Errors](/errors). Common cases: unknown or non-embedding model (`400`), empty string in `input` (`400`), upstream rate limit (`429`).