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

# Text Embeddings

> Convert text to vector embeddings

# Text Embeddings

The Embeddings API converts text into high-dimensional vector representations, useful for semantic search, clustering, and RAG applications.

## Endpoint

```
POST https://api.mixroute.ai/v1/embeddings
```

## Authentication

```
Authorization: Bearer sk-xxxxxxxxxx
```

## Request Body

| Parameter         | Type         | Required | Description                         |
| ----------------- | ------------ | -------- | ----------------------------------- |
| `model`           | string       | Yes      | Embedding model ID                  |
| `input`           | string/array | Yes      | Text(s) to embed                    |
| `encoding_format` | string       | No       | Output format: `float` or `base64`  |
| `dimensions`      | integer      | No       | Output dimensions (model-dependent) |

## Example Request

### Single Text

```bash theme={null}
curl -X POST https://api.mixroute.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox jumps over the lazy dog."
  }'
```

### Batch Texts

```bash theme={null}
curl -X POST https://api.mixroute.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "First document text",
      "Second document text",
      "Third document text"
    ]
  }'
```

## Custom Dimensions

Reduce embedding dimensions for efficiency:

```bash theme={null}
curl -X POST https://api.mixroute.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "text-embedding-3-large",
    "input": "Sample text for embedding",
    "dimensions": 512
  }'
```

## Supported Models

| Model                    | Dimensions | Description          |
| ------------------------ | ---------- | -------------------- |
| `text-embedding-3-small` | 1536       | Fast, cost-effective |
| `text-embedding-3-large` | 3072       | Higher accuracy      |
| `text-embedding-ada-002` | 1536       | Legacy model         |

## Use Cases

### Semantic Search

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

# Compare query embedding with document embeddings
similarities = [cosine_similarity(query_embedding, doc) for doc in doc_embeddings]
```

### Document Clustering

```python theme={null}
from sklearn.cluster import KMeans

# Cluster documents by embedding similarity
kmeans = KMeans(n_clusters=5)
clusters = kmeans.fit_predict(embeddings)
```

## Best Practices

* **Batch requests**: Send multiple texts in one request for efficiency
* **Normalize vectors**: Normalize embeddings for consistent similarity scores
* **Choose dimensions**: Use smaller dimensions when storage/speed matters
* **Chunk long texts**: Split long documents into meaningful chunks before embedding

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.mixroute.ai/v1/embeddings \
    --header 'Authorization: Bearer sk-xxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "text-embedding-3-small",
      "input": "Hello, world"
    }'
  ```

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

  client = OpenAI(
      api_key="sk-xxxxxxxxxx",
      base_url="https://api.mixroute.ai/v1"
  )

  response = client.embeddings.create(
      model="text-embedding-3-small",
      input="Hello, world"
  )
  print(response.data[0].embedding)
  ```

  ```javascript JavaScript theme={null}
  const OpenAI = require('openai');

  const client = new OpenAI({
    apiKey: 'sk-xxxxxxxxxx',
    baseURL: 'https://api.mixroute.ai/v1'
  });

  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: 'Hello, world'
  });
  console.log(response.data[0].embedding);
  ```

  ```php PHP theme={null}
  <?php
  $client = new GuzzleHttp\Client();
  $response = $client->post('https://api.mixroute.ai/v1/embeddings', [
      'headers' => [
          'Authorization' => 'Bearer sk-xxxxxxxxxx',
          'Content-Type' => 'application/json',
      ],
      'json' => [
          'model' => 'text-embedding-3-small',
          'input' => 'Hello, world'
      ]
  ]);
  echo $response->getBody();
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      openai "github.com/sashabaranov/go-openai"
  )

  func main() {
      config := openai.DefaultConfig("sk-xxxxxxxxxx")
      config.BaseURL = "https://api.mixroute.ai/v1"
      client := openai.NewClientWithConfig(config)

      resp, _ := client.CreateEmbeddings(
          context.Background(),
          openai.EmbeddingRequest{
              Model: "text-embedding-3-small",
              Input: []string{"Hello, world"},
          },
      )
      fmt.Println(resp.Data[0].Embedding)
  }
  ```

  ```java Java theme={null}
  import java.net.http.*;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  String json = """
      {
        "model": "text-embedding-3-small",
        "input": "Hello, world"
      }
      """;
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.mixroute.ai/v1/embeddings"))
      .header("Authorization", "Bearer sk-xxxxxxxxxx")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.mixroute.ai/v1/embeddings')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer sk-xxxxxxxxxx'
  request['Content-Type'] = 'application/json'
  request.body = {
    model: 'text-embedding-3-small',
    input: 'Hello, world'
  }.to_json

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

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