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

# Embeddings

> Generate numerical vector representations of text for search, clustering, and classification.

## Overview

Embeddings are numerical vector representations of text that capture semantic meaning. This allows you to perform mathematical operations on text, such as measuring the "distance" or "similarity" between different pieces of text.

They are a foundational component for a wide range of AI applications, including semantic search, clustering, recommendations, anomaly detection, and classification. YouRouter provides access to leading embedding models through a simple, unified API.

## Usage

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

  client = OpenAI(
      api_key=os.environ["YOUROUTER_API_KEY"],
      base_url="https://api.yourouter.ai/v1"
  )

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

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

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

  const openai = new OpenAI({
    apiKey: process.env.YOUROUTER_API_KEY,
    baseURL: 'https://api.yourouter.ai/v1',
  });

  async function main() {
    const response = await openai.embeddings.create({
      input: "Your text string goes here",
      model: "text-embedding-ada-002",
    });
    console.log(response.data[0].embedding);
  }

  main();
  ```

  ```bash cURL theme={null}
  curl https://api.yourouter.ai/v1/embeddings \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $YOUROUTER_API_KEY" \
    -d '{
      "input": "The quick brown fox jumps over the lazy dog",
      "model": "text-embedding-ada-002"
    }'
  ```
</CodeGroup>

### Batch Processing

For efficiency, you can pass an array of strings to the `input` parameter to generate multiple embeddings in a single request.

<CodeGroup>
  ```python theme={null}
  response = client.embeddings.create(
      input=[
          "First sentence to embed.",
          "Another sentence for batch processing."
      ],
      model="text-embedding-ada-002"
  )

  for i, data in enumerate(response.data):
      print(f"Embedding for input {i+1}: {len(data.embedding)} dimensions")
  ```
</CodeGroup>

## Parameters

<ResponseField name="input" type="string or array" required>
  The input text or texts to embed. Can be a single string or an array of strings for batch processing.
</ResponseField>

<ResponseField name="model" type="string" required>
  The ID of the embedding model to use (e.g., `text-embedding-ada-002`).
</ResponseField>

<ResponseField name="encoding_format" type="string" default="float">
  The format to return the embeddings in. Can be `float` or `base64`. Base64 is useful for reducing JSON payload size.
</ResponseField>

<ResponseField name="user" type="string">
  A unique identifier representing your end-user, which can help to monitor and detect abuse.
</ResponseField>

## Use Cases

### Semantic Search

Instead of keyword matching, semantic search finds results that are contextually related to the user's query, even if they don't share the exact same words. This is achieved by comparing the vector embedding of the query with the embeddings of your documents.

```python theme={null}
import numpy as np
from scipy.spatial.distance import cosine

documents = [
    "The sky is blue and beautiful.",
    "The sun is the star at the center of the Solar System.",
    "Artificial intelligence will reshape our world."
]

doc_embeddings = [
    client.embeddings.create(input=doc, model="text-embedding-ada-002").data[0].embedding
    for doc in documents
]

query = "What is the future of AI?"
query_embedding = client.embeddings.create(input=query, model="text-embedding-ada-002").data[0].embedding

similarities = [1 - cosine(query_embedding, doc_emb) for doc_emb in doc_embeddings]
most_similar_index = np.argmax(similarities)

print(f"Query: '{query}'")
print(f"Most similar document: '{documents[most_similar_index]}'")
```

### Classification & Clustering

Embeddings are powerful features for machine learning models. You can use them to train a classifier (e.g., for sentiment analysis or topic categorization) or to group similar items together using clustering algorithms.

## Best Practices

<AccordionGroup>
  <Accordion title="Preprocessing">
    While modern embedding models are robust, for some applications, basic preprocessing like removing irrelevant characters or normalizing text can still be beneficial. However, avoid aggressive stemming or stop-word removal, as it can strip away important context.
  </Accordion>

  <Accordion title="Batching for Efficiency">
    When you need to embed multiple pieces of text, always use the batching capability by passing an array of strings. This significantly reduces latency by minimizing the number of network round-trips.
  </Accordion>

  <Accordion title="Caching">
    If your application frequently embeds the same text (e.g., popular search queries or document titles), implement a caching layer (like Redis or an in-memory cache) to store and retrieve embeddings. This reduces API calls, lowers costs, and improves performance.
  </Accordion>
</AccordionGroup>

## Scaling Up: Vector Databases

For any application with more than a few thousand embeddings, performing a brute-force similarity search (like the example above) becomes slow and inefficient. This is where vector databases come in.

Vector databases are specialized systems designed to store and search through millions or even billions of vector embeddings at high speed. They use sophisticated indexing algorithms (like HNSW or IVF) to perform Approximate Nearest Neighbor (ANN) searches, providing a an excellent balance between speed and accuracy.

Popular choices include:

* **Cloud-based**: Pinecone, Zilliz Cloud
* **Open-source / Self-hosted**: Weaviate, Milvus, Chroma, Qdrant