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

# Generate text embeddings using TokModel's gateway API

> Convert text into dense vector embeddings via TokModel's /v1/embeddings endpoint — compatible with any OpenAI embeddings client.

The `/v1/embeddings` endpoint converts text into numerical vectors that capture semantic meaning. You can embed a single string or a batch of strings in one request. The resulting vectors are suitable for semantic search, retrieval-augmented generation (RAG), clustering, and classification tasks.

## Authentication

Include your API key in every request:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Send an embeddings request

Provide an `input` (a string or array of strings) and a `model`. TokModel routes the request to the specified embedding model and returns one vector per input item.

<CodeGroup>
  ```bash curl theme={null}
  curl https://tokmodel.com/v1/embeddings \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/text-embedding-3-small",
      "input": "The quick brown fox jumps over the lazy dog."
    }'
  ```

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

  client = OpenAI(
      api_key="YOUR_API_KEY",
      base_url="https://tokmodel.com/v1",
  )

  response = client.embeddings.create(
      model="openai/text-embedding-3-small",
      input="The quick brown fox jumps over the lazy dog.",
  )

  vector = response.data[0].embedding
  print(f"Embedding dimension: {len(vector)}")
  ```

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

  const client = new OpenAI({
    apiKey: "YOUR_API_KEY",
    baseURL: "https://tokmodel.com/v1",
  });

  const response = await client.embeddings.create({
    model: "openai/text-embedding-3-small",
    input: "The quick brown fox jumps over the lazy dog.",
  });

  const vector = response.data[0].embedding;
  console.log(`Embedding dimension: ${vector.length}`);
  ```
</CodeGroup>

## Embed multiple inputs in one request

Pass an array of strings to `input` to embed a batch in a single API call. The response contains one entry per input, in the same order.

<CodeGroup>
  ```bash curl theme={null}
  curl https://tokmodel.com/v1/embeddings \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/text-embedding-3-small",
      "input": [
        "How do I reset my password?",
        "Where can I find my invoices?",
        "How do I cancel my subscription?"
      ]
    }'
  ```

  ```python python theme={null}
  texts = [
      "How do I reset my password?",
      "Where can I find my invoices?",
      "How do I cancel my subscription?",
  ]

  response = client.embeddings.create(
      model="openai/text-embedding-3-small",
      input=texts,
  )

  for i, item in enumerate(response.data):
      print(f"Input {i}: {len(item.embedding)}-dimensional vector")
  ```
</CodeGroup>

## Example response

Each object in the `data` array corresponds to one input string. The `embedding` field contains the raw float vector.

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797347,
        "..."
      ]
    }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}
```

<Note>
  The `embedding` array above is truncated for readability. Real vectors typically contain 512 to 3072 dimensions depending on the model.
</Note>

## Compute cosine similarity

After embedding two pieces of text, compare them with cosine similarity. A score close to `1.0` means the texts are semantically similar.

```python python theme={null}
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=[
        "How do I reset my password?",
        "I forgot my password, what should I do?",
    ],
)

vec_a = response.data[0].embedding
vec_b = response.data[1].embedding

score = cosine_similarity(vec_a, vec_b)
print(f"Similarity: {score:.4f}")  # e.g. 0.9312
```

## Common use cases

**Semantic search** — embed a user query and compare it against pre-embedded documents to find the most relevant results, even when the exact words differ.

**Retrieval-augmented generation (RAG)** — embed your knowledge base and retrieve the top-k matching chunks before passing them to a chat model as context.

**Clustering** — group similar documents together by clustering their vectors using algorithms like k-means without any labeled training data.

**Classification** — train a lightweight classifier on top of embeddings to categorize text into predefined labels.