> ## 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

```text theme={null}
POST https://api.mixroute.ai/v1/embeddings
```

## Authentication

```text theme={null}
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` |
| `input_type` | string | Cohere only | search\_document, search\_query, classification, or clustering. |
| `dimensions` | integer | No | Output dimensions for models/routes that expose this field, such as OpenAI text-embedding-3. Do not assume native Cohere output\_dimension has the same mapping. |

## 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 |
| `embed-v4.0` | 1536 | Cohere embedding model for multilingual retrieval, with long-context text support. |
| `embed-english-v3.0` | 1024 | Cohere text embedding model optimized for English retrieval. |
| `embed-multilingual-v3.0` | 1024 | Cohere text embedding model for cross-language retrieval. |

## Cohere Embeddings

Use `input_type=search_document` for stored documents and `search_query` for queries. Keep model and dimensions identical on both sides. The text-compatible endpoint returns vectors in `data[].embedding`; native image/PDF embedding inputs are not interchangeable with this text input schema.

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/embeddings" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "embed-v4.0",
  "input": [
    "An API reference for developers."
  ],
  "input_type": "search_document",
  "encoding_format": "float"
}'
```

## 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>


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