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

# Create Embeddings

> Create vector embeddings from text

```
POST /v1/embeddings
```

Creates an embedding vector representing the input text. Embeddings are useful for semantic search, clustering, and similarity comparison.

## Request Body

<ParamField body="model" type="string" required>
  The embedding model to use (e.g., `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`).
</ParamField>

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

<ParamField body="encoding_format" type="string" default="float">
  The format to return embeddings in. Options: `float` or `base64`.
</ParamField>

<ParamField body="dimensions" type="integer">
  The number of dimensions for the output embeddings. Only supported by some models.
</ParamField>

## Response

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

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

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

    <ResponseField name="index" type="integer">
      The index of the embedding in the input array.
    </ResponseField>

    <ResponseField name="embedding" type="array">
      The embedding vector (array of floats).
    </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="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

### Single Text Embedding

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

  client = OpenAI(
      api_key="sk-voidai-your_key_here",
      base_url="https://api.voidai.app/v1"
  )

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

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

  ```typescript TypeScript theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    apiKey: 'sk-voidai-your_key_here',
    baseURL: 'https://api.voidai.app/v1'
  });

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

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

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

### Batch Embeddings

<CodeGroup>
  ```python Python theme={null}
  texts = [
      "How do I reset my password?",
      "What are your pricing plans?",
      "How can I contact support?"
  ]

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

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

  ```typescript TypeScript theme={null}
  const texts = [
    'How do I reset my password?',
    'What are your pricing plans?',
    'How can I contact support?'
  ];

  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: texts
  });

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

  ```bash cURL theme={null}
  curl https://api.voidai.app/v1/embeddings \
    -H "Authorization: Bearer sk-voidai-your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "text-embedding-3-small",
      "input": [
        "How do I reset my password?",
        "What are your pricing plans?",
        "How can I contact support?"
      ]
    }'
  ```
</CodeGroup>

### Custom Dimensions

<CodeGroup>
  ```python Python theme={null}
  # Use smaller dimension for efficiency
  response = client.embeddings.create(
      model="text-embedding-3-large",
      input="Your text here",
      dimensions=256
  )

  embedding = response.data[0].embedding
  print(f"Reduced dimension: {len(embedding)}")  # 256
  ```

  ```typescript TypeScript theme={null}
  const response = await client.embeddings.create({
    model: 'text-embedding-3-large',
    input: 'Your text here',
    dimensions: 256
  });

  console.log(`Reduced dimension: ${response.data[0].embedding.length}`);  // 256
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0095, 0.0152, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Semantic Search" icon="magnifying-glass">
    Find similar content by comparing embedding distances.
  </Card>

  <Card title="Clustering" icon="object-group">
    Group similar documents together based on embeddings.
  </Card>

  <Card title="Classification" icon="tags">
    Use embeddings as features for ML classifiers.
  </Card>

  <Card title="Recommendations" icon="thumbs-up">
    Find similar items for recommendation systems.
  </Card>
</CardGroup>

## Similarity Search Example

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

client = OpenAI(
    api_key="sk-voidai-your_key_here",
    base_url="https://api.voidai.app/v1"
)

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

# Create embeddings for documents
documents = [
    "Python is a programming language",
    "JavaScript runs in the browser",
    "Machine learning uses neural networks"
]

doc_embeddings = client.embeddings.create(
    model="text-embedding-3-small",
    input=documents
).data

# Search query
query = "How do I code in Python?"
query_embedding = client.embeddings.create(
    model="text-embedding-3-small",
    input=query
).data[0].embedding

# Find most similar document
similarities = [
    cosine_similarity(query_embedding, doc.embedding)
    for doc in doc_embeddings
]

best_match_idx = np.argmax(similarities)
print(f"Best match: {documents[best_match_idx]}")
print(f"Similarity: {similarities[best_match_idx]:.4f}")
```

## Model Comparison

| Model                    | Dimensions | Best For                                 |
| ------------------------ | ---------- | ---------------------------------------- |
| `text-embedding-3-small` | 1536       | Cost-effective, general use              |
| `text-embedding-3-large` | 3072       | Highest quality, customizable dimensions |
| `text-embedding-ada-002` | 1536       | Legacy, broad compatibility              |