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

# Embeddings

> Create embeddings for text using OpenAI-compatible and alternative embedding models

## Overview

Create embeddings for text using OpenAI-compatible and alternative embedding models. NanoGPT supports 20+ embedding models (and this list changes over time); use `GET /api/v1/embedding-models` for the source-of-truth list.

## Available Models

### OpenAI Models

* `text-embedding-3-small` - 1536 dimensions, \$0.02/1M tokens - Most cost-effective with dimension reduction support
* `text-embedding-3-large` - 3072 dimensions, \$0.13/1M tokens - Highest performance with dimension reduction support
* `text-embedding-ada-002` - 1536 dimensions, \$0.10/1M tokens - Legacy model

### Alternative Models

**Multilingual:**

* `BAAI/bge-m3` - 1024 dimensions, \$0.01/1M tokens - Multilingual support
* `jina-clip-v1` - 768 dimensions, \$0.04/1M tokens - Multimodal CLIP embeddings

**Language-Specific:**

* `BAAI/bge-base-en-v1.5` - 768 dimensions, \$0.01/1M tokens - English (base)
* `BAAI/bge-large-en-v1.5` - 1024 dimensions, \$0.01/1M tokens - English optimized
* `BAAI/bge-large-zh-v1.5` - 1024 dimensions, \$0.01/1M tokens - Chinese optimized
* `jina-embeddings-v2-base-en` - 768 dimensions, \$0.05/1M tokens - English
* `jina-embeddings-v2-base-de` - 768 dimensions, \$0.05/1M tokens - German
* `jina-embeddings-v2-base-zh` - 768 dimensions, \$0.05/1M tokens - Chinese
* `jina-embeddings-v2-base-es` - 768 dimensions, \$0.05/1M tokens - Spanish

**Specialized:**

* `BAAI/bge-reranker-large` - 1024 dimensions, \$0.01/1M tokens - Reranker
* `jina-embeddings-v2-base-code` - 768 dimensions, \$0.05/1M tokens - Code embeddings
* `Baichuan-Text-Embedding` - 1024 dimensions, \$0.088/1M tokens
* `netease-youdao/bce-embedding-base_v1` - 1024 dimensions, \$0.02/1M tokens
* `zhipu-embedding-2` - 1024 dimensions, \$0.07/1M tokens
* `Qwen/Qwen3-Embedding-0.6B` - 1024 dimensions, \$0.01/1M tokens - Supports dimension reduction
* `Qwen/Qwen3-Embedding-4B` - 1536 dimensions, \$0.03/1M tokens - Supports dimension reduction
* `Qwen/Qwen3-Embedding-8B` - 1536 dimensions, \$0.05/1M tokens - Supports dimension reduction
* `jina-embeddings-v3` - 1024 dimensions, \$0.10/1M tokens
* `jina-embeddings-v4` - 2048 dimensions, \$0.10/1M tokens
* `gemini-embedding-001` - 3072 dimensions, \$0.15/1M tokens
* `doubao-embedding-large-text-240915` - 4096 dimensions, \$0.10/1M tokens

## Request Parameters

| Parameter         | Type            | Required | Description                                                |
| ----------------- | --------------- | -------- | ---------------------------------------------------------- |
| `input`           | string or array | Yes      | Single text string or array of up to 2048 strings to embed |
| `model`           | string          | Yes      | ID of the embedding model to use                           |
| `encoding_format` | string          | No       | Format for embeddings: `"float"` (default) or `"base64"`   |
| `dimensions`      | integer         | No       | Reduce embedding dimensions (only for supported models)    |
| `user`            | string          | No       | Optional identifier for tracking usage                     |

## Response Format

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.023, -0.012, 0.045, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
```

## Code Examples

### Python with OpenAI SDK

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

# Initialize client pointing to NanoGPT
client = OpenAI(
    api_key="YOUR_NANOGPT_API_KEY",
    base_url="https://nano-gpt.com/api/v1"
)

# Create embedding
response = client.embeddings.create(
    input="Your text to embed",
    model="text-embedding-3-small"
)

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

### JavaScript/TypeScript

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

// Initialize client pointing to NanoGPT
const openai = new OpenAI({
    apiKey: 'YOUR_NANOGPT_API_KEY',
    baseURL: 'https://nano-gpt.com/api/v1'
});

// Create embedding
const response = await openai.embeddings.create({
    input: "Your text to embed",
    model: "text-embedding-3-small"
});

// Access the embedding
const embedding = response.data[0].embedding;
console.log(`Embedding dimensions: ${embedding.length}`);
```

### cURL

```bash theme={null}
curl https://nano-gpt.com/api/v1/embeddings \
  -H "Authorization: Bearer YOUR_NANOGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Your text to embed",
    "model": "text-embedding-3-small"
  }'
```

### Batch Processing

```python theme={null}
# Process multiple texts in a single request
texts = [
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
]

response = client.embeddings.create(
    input=texts,  # Pass array of strings
    model="text-embedding-3-small"
)

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

### Dimension Reduction

For models that support it (`text-embedding-3-small`, `text-embedding-3-large`, `Qwen/Qwen3-Embedding-0.6B`, `Qwen/Qwen3-Embedding-4B`, `Qwen/Qwen3-Embedding-8B`):

```python theme={null}
# Reduce dimensions to 256 for faster similarity comparisons
response = client.embeddings.create(
    input="Your text to embed",
    model="text-embedding-3-small",
    dimensions=256  # Reduce from 1536 to 256
)
```

## Use Cases

### Semantic Search

```python theme={null}
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

# Create embeddings for your documents
documents = ["Document 1 text", "Document 2 text", "Document 3 text"]
doc_embeddings = []

for doc in documents:
    response = client.embeddings.create(input=doc, model="text-embedding-3-small")
    doc_embeddings.append(response.data[0].embedding)

# Create embedding for search query
query = "Search query text"
query_response = client.embeddings.create(input=query, model="text-embedding-3-small")
query_embedding = query_response.data[0].embedding

# Calculate similarities
similarities = cosine_similarity([query_embedding], doc_embeddings)[0]

# Find most similar documents
top_matches = np.argsort(similarities)[::-1][:3]
for idx in top_matches:
    print(f"Document {idx}: {similarities[idx]:.3f} similarity")
```

### RAG (Retrieval Augmented Generation)

```python theme={null}
# 1. Embed and store your knowledge base
knowledge_base = [
    {"text": "Fact 1...", "embedding": None},
    {"text": "Fact 2...", "embedding": None},
]

for item in knowledge_base:
    response = client.embeddings.create(
        input=item["text"], 
        model="text-embedding-3-small"
    )
    item["embedding"] = response.data[0].embedding

# 2. For a user query, find relevant context
user_query = "What is...?"
query_response = client.embeddings.create(
    input=user_query,
    model="text-embedding-3-small"
)
query_embedding = query_response.data[0].embedding

# 3. Find most relevant facts
# relevant_facts = find_similar_texts(query_embedding, knowledge_base, top_k=3)

# 4. Use retrieved context with chat completion
chat_response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": f"Context: {relevant_facts}"},
        {"role": "user", "content": user_query}
    ]
)
```

## Best Practices

### Model Selection

* **General English text**: Use `text-embedding-3-small` for best price/performance
* **Maximum accuracy**: Use `text-embedding-3-large`
* **Multilingual**: Use `BAAI/bge-m3` or language-specific Jina models
* **Code**: Use `jina-embeddings-v2-base-code`
* **Budget-conscious**: Use BAAI models at \$0.01/1M tokens

### Performance Optimization

* **Batch requests**: Send up to 2048 texts in a single request
* **Use dimension reduction**: Reduce dimensions for faster similarity calculations when exact precision isn't critical
* **Cache embeddings**: Store computed embeddings to avoid re-processing identical texts
* **Choose appropriate models**: Don't use 3072-dimension models if 768 dimensions suffice

### Cost Optimization

* **Monitor token usage**: Track the `usage` field in responses
* **Use smaller models**: Start with `text-embedding-3-small` before upgrading
* **Implement caching**: Avoid re-embedding identical content
* **Batch processing**: Reduce API call overhead

## Rate Limits

Rate limits vary by endpoint and account. See [Rate Limits](/api-reference/miscellaneous/rate-limits).

## Error Handling

The API returns standard HTTP status codes and OpenAI-compatible error responses:

See also: [Error Handling](/api-reference/miscellaneous/error-handling).

```json theme={null}
{
  "error": {
    "message": "Invalid model specified",
    "type": "invalid_request_error",
    "param": "model",
    "code": null
  }
}
```

Common error codes:

* `401`: Invalid or missing API key
* `400`: Invalid request parameters
* `429`: Rate limit exceeded
* `500`: Server error


## OpenAPI

````yaml POST /v1/embeddings
openapi: 3.1.0
info:
  title: NanoGPT API
  description: >-
    API documentation for the NanoGPT language, image, video, speech-to-text,
    and text-to-speech generation services
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://nano-gpt.com/api
    description: NanoGPT API Server
security: []
paths:
  /v1/embeddings:
    post:
      description: >-
        Create embeddings for text using OpenAI-compatible and alternative
        embedding models
      requestBody:
        description: Parameters for creating embeddings
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
        required: true
      responses:
        '200':
          description: Embedding response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing API key
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal Server Error
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    EmbeddingRequest:
      type: object
      required:
        - input
        - model
      properties:
        input:
          oneOf:
            - type: string
              description: Single text string to embed
            - type: array
              description: Array of text strings to embed (max 2048)
              items:
                type: string
              maxItems: 2048
          description: Text to embed - single string or array of up to 2048 strings
        model:
          type: string
          description: ID of the embedding model to use
          example: text-embedding-3-small
        encoding_format:
          type: string
          description: Format for embeddings
          enum:
            - float
            - base64
          default: float
        dimensions:
          type: integer
          description: Reduce embedding dimensions (only for supported models)
          example: 256
        user:
          type: string
          description: Optional identifier for tracking usage
    EmbeddingResponse:
      type: object
      required:
        - object
        - data
        - model
        - usage
      properties:
        object:
          type: string
          description: Always 'list' for embeddings
          example: list
        data:
          type: array
          description: Array of embedding objects
          items:
            type: object
            required:
              - object
              - index
              - embedding
            properties:
              object:
                type: string
                description: Always 'embedding'
                example: embedding
              index:
                type: integer
                description: Index of this embedding in the batch
                example: 0
              embedding:
                oneOf:
                  - type: array
                    description: Embedding vector as array of floats
                    items:
                      type: number
                  - type: string
                    description: Base64-encoded embedding vector
        model:
          type: string
          description: Model used for embeddings
          example: text-embedding-3-small
        usage:
          type: object
          required:
            - prompt_tokens
            - total_tokens
          properties:
            prompt_tokens:
              type: integer
              description: Number of tokens in the input
              example: 8
            total_tokens:
              type: integer
              description: Total tokens processed
              example: 8
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````