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

# Embeddings

> Generate vector embeddings for text inputs

## Endpoint

```
POST /v1/embeddings
```

Generate vector embeddings for one or more text inputs. Compatible with the OpenAI Embeddings API.

<Note>
  Embeddings support varies by provider. Gemini and Ollama provide the best embedding model availability.
</Note>

## Request Body

<ParamField body="input" type="string | array" required>
  Input text or array of texts to generate embeddings for.
</ParamField>

<ParamField body="model" type="string" required>
  The embedding model to use. Examples:

  * `gemini:text-embedding-004`
  * `ollama:nomic-embed-text`
  * `switchai:text-embedding-3-small`
</ParamField>

<ParamField body="encoding_format" type="string">
  Format for the embeddings: `float` or `base64` (default: `float`)
</ParamField>

<ParamField body="dimensions" type="integer">
  Number of dimensions for the embedding (model-dependent)
</ParamField>

## Response Format

<ResponseField name="object" type="string">
  Always `list`
</ResponseField>

<ResponseField name="data" type="array">
  Array of embedding objects

  <Expandable title="Embedding Object Properties">
    <ResponseField name="object" type="string">
      Always `embedding`
    </ResponseField>

    <ResponseField name="index" type="integer">
      Position in the input array
    </ResponseField>

    <ResponseField name="embedding" type="array">
      Vector of floating point numbers representing the embedding
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string">
  The model used to generate embeddings
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics

  <Expandable title="Usage Properties">
    <ResponseField name="prompt_tokens" type="integer">
      Number of tokens in the input
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total tokens processed
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Basic Request

<CodeGroup>
  ```bash cURL theme={null}
  curl http://localhost:18080/v1/embeddings \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sk-test-123" \
    -d '{
      "model": "gemini:text-embedding-004",
      "input": "The quick brown fox jumps over the lazy dog"
    }'
  ```

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

  client = OpenAI(
      base_url="http://localhost:18080/v1",
      api_key="sk-test-123"
  )

  response = client.embeddings.create(
      model="gemini:text-embedding-004",
      input="The quick brown fox jumps over the lazy dog"
  )

  embedding = response.data[0].embedding
  print(f"Embedding dimensions: {len(embedding)}")
  print(f"First 5 values: {embedding[:5]}")
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'http://localhost:18080/v1',
    apiKey: 'sk-test-123'
  });

  const response = await client.embeddings.create({
    model: 'gemini:text-embedding-004',
    input: 'The quick brown fox jumps over the lazy dog'
  });

  const embedding = response.data[0].embedding;
  console.log(`Embedding dimensions: ${embedding.length}`);
  console.log(`First 5 values: ${embedding.slice(0, 5)}`);
  ```
</CodeGroup>

### Batch Embeddings

Generate embeddings for multiple texts:

<CodeGroup>
  ```python Python theme={null}
  response = client.embeddings.create(
      model="gemini:text-embedding-004",
      input=[
          "Machine learning is a subset of AI",
          "Deep learning uses neural networks",
          "Natural language processing enables text understanding"
      ]
  )

  for i, data in enumerate(response.data):
      print(f"Text {i}: {len(data.embedding)} dimensions")
  ```

  ```javascript Node.js theme={null}
  const response = await client.embeddings.create({
    model: 'gemini:text-embedding-004',
    input: [
      'Machine learning is a subset of AI',
      'Deep learning uses neural networks',
      'Natural language processing enables text understanding'
    ]
  });

  response.data.forEach((data, i) => {
    console.log(`Text ${i}: ${data.embedding.length} dimensions`);
  });
  ```
</CodeGroup>

### Similarity Search

Use embeddings for semantic similarity:

```python theme={null}
import numpy as np
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="sk-test-123"
)

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

# Generate embeddings
response = client.embeddings.create(
    model="gemini:text-embedding-004",
    input=[
        "What is machine learning?",
        "How do I train a neural network?",
        "Best pizza toppings"
    ]
)

embeddings = [d.embedding for d in response.data]

# Compare first query to others
query = embeddings[0]
similarity_1 = cosine_similarity(query, embeddings[1])
similarity_2 = cosine_similarity(query, embeddings[2])

print(f"ML vs Neural Networks: {similarity_1:.3f}")
print(f"ML vs Pizza: {similarity_2:.3f}")
```

## Supported Models

### Gemini Embeddings

| Model                                | Dimensions | Max Input   | Description            |
| ------------------------------------ | ---------- | ----------- | ---------------------- |
| `gemini:text-embedding-004`          | 768        | 2048 tokens | Latest embedding model |
| `gemini:text-embedding-preview-1009` | 768        | 2048 tokens | Preview model          |
| `gemini:embedding-001`               | 768        | 2048 tokens | Legacy model           |

### Ollama Embeddings

Ollama provides various open-source embedding models:

```bash theme={null}
# Pull embedding model
ollama pull nomic-embed-text

# Use in request
curl http://localhost:18080/v1/embeddings \
  -H "Authorization: Bearer sk-test-123" \
  -d '{
    "model": "ollama:nomic-embed-text",
    "input": "Sample text"
  }'
```

### switchAI Embeddings

switchAI provides access to multiple embedding providers:

```python theme={null}
response = client.embeddings.create(
    model="switchai:text-embedding-3-small",
    input="Text to embed"
)
```

## Response Example

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0123,
        -0.0234,
        0.0345,
        // ... 765 more values
      ]
    }
  ],
  "model": "gemini:text-embedding-004",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
```

## Use Cases

### Semantic Search

Find similar documents:

```python theme={null}
# 1. Embed all documents
documents = ["doc1 text", "doc2 text", "doc3 text"]
response = client.embeddings.create(
    model="gemini:text-embedding-004",
    input=documents
)
doc_embeddings = [d.embedding for d in response.data]

# 2. Embed query
query = "search query"
query_response = client.embeddings.create(
    model="gemini:text-embedding-004",
    input=query
)
query_embedding = query_response.data[0].embedding

# 3. Find most similar
similarities = [
    cosine_similarity(query_embedding, doc_emb)
    for doc_emb in doc_embeddings
]
best_match = documents[np.argmax(similarities)]
```

### Clustering

Group similar texts:

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

# Generate embeddings
texts = ["text1", "text2", "text3", ...]
response = client.embeddings.create(
    model="gemini:text-embedding-004",
    input=texts
)
embeddings = np.array([d.embedding for d in response.data])

# Cluster
kmeans = KMeans(n_clusters=3)
labels = kmeans.fit_predict(embeddings)
```

### Recommendation Systems

Recommend similar items:

```python theme={null}
# Embed user preferences and item descriptions
user_pref = "I like action movies with great CGI"
items = ["Movie A: Action-packed blockbuster", "Movie B: Romantic drama", ...]

response = client.embeddings.create(
    model="gemini:text-embedding-004",
    input=[user_pref] + items
)

user_emb = response.data[0].embedding
item_embs = [d.embedding for d in response.data[1:]]

# Rank by similarity
scores = [cosine_similarity(user_emb, item) for item in item_embs]
top_items = sorted(zip(items, scores), key=lambda x: x[1], reverse=True)
```

## Error Handling

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI, APIError

  client = OpenAI(
      base_url="http://localhost:18080/v1",
      api_key="sk-test-123"
  )

  try:
      response = client.embeddings.create(
          model="invalid-model",
          input="Test text"
      )
  except APIError as e:
      print(f"API error: {e.message}")
      print(f"Status: {e.status_code}")
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'http://localhost:18080/v1',
    apiKey: 'sk-test-123'
  });

  try {
    const response = await client.embeddings.create({
      model: 'invalid-model',
      input: 'Test text'
    });
  } catch (error) {
    console.error('API error:', error.message);
    console.error('Status:', error.status);
  }
  ```
</CodeGroup>

## Performance Tips

<AccordionGroup>
  <Accordion title="Batch Processing">
    Process multiple texts in a single request for better throughput:

    ```python theme={null}
    # Good: Single request for 10 texts
    response = client.embeddings.create(
        model="gemini:text-embedding-004",
        input=texts  # List of 10 texts
    )

    # Avoid: 10 separate requests
    for text in texts:
        response = client.embeddings.create(
            model="gemini:text-embedding-004",
            input=text
        )
    ```
  </Accordion>

  <Accordion title="Caching">
    Cache embeddings for frequently used texts:

    ```python theme={null}
    import pickle

    # Save embeddings
    with open('embeddings.pkl', 'wb') as f:
        pickle.dump(embeddings, f)

    # Load cached embeddings
    with open('embeddings.pkl', 'rb') as f:
        embeddings = pickle.load(f)
    ```
  </Accordion>

  <Accordion title="Model Selection">
    Choose appropriate model for your use case:

    * **Gemini**: Best for multilingual and semantic search
    * **Ollama**: Best for privacy and offline usage
    * **switchAI**: Best for unified access to multiple providers
  </Accordion>
</AccordionGroup>

## Limitations

| Provider | Max Tokens      | Dimensions      | Notes                   |
| -------- | --------------- | --------------- | ----------------------- |
| Gemini   | 2048            | 768             | Supports batch requests |
| Ollama   | Model-dependent | Model-dependent | Local processing        |
| Claude   | N/A             | N/A             | No embedding support    |

## Next Steps

<CardGroup cols={2}>
  <Card title="Models" icon="cube" href="/api/models">
    Discover available embedding models
  </Card>

  <Card title="Chat Completions" icon="messages" href="/api/chat-completions">
    Use embeddings for RAG systems
  </Card>
</CardGroup>