# How to Generate Embeddings Using FreeLLMAPI: Complete API Guide

> Learn how to generate embeddings with FreeLLMAPI. This guide covers the OpenAI-compatible API, routing to multiple providers like Gemini and NVIDIA, and using the runEmbeddings function for vector representations.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: api-guide
- Published: 2026-08-26

---

**FreeLLMAPI exposes an OpenAI-compatible `/embeddings` endpoint that routes requests to multiple providers (OpenAI, Gemini, NVIDIA, etc.) and returns normalized vector representations through the `runEmbeddings` service function.**

The FreeLLMAPI repository (`tashfeenahmed/freellmapi`) provides a unified gateway for generating text embeddings across diverse AI providers without managing multiple API integrations. By implementing a provider-agnostic architecture with automatic fail-over, the service allows developers to generate embeddings using a single endpoint while maintaining full compatibility with the OpenAI API specification.

## FreeLLMAPI Embeddings Architecture

The embeddings system follows a layered architecture that abstracts provider-specific implementations behind a standardized interface. Understanding these components helps debug routing decisions and optimize request handling.

### The API Router ([`server/src/routes/embeddings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/embeddings.ts))

The entry point for all embedding requests resides in [`server/src/routes/embeddings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/embeddings.ts). This Express router exposes both `POST /api/embeddings` and the proxy endpoint `POST /embeddings`, validating incoming JSON payloads before forwarding them to the core service. The router expects a request body containing `input` (string or array) and an optional `model` parameter.

### The Embeddings Service ([`server/src/services/embeddings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/embeddings.ts))

The `runEmbeddings` function in [`server/src/services/embeddings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/embeddings.ts) orchestrates the generation flow. This service performs four critical operations:

1. **Model Resolution**: Queries the SQLite catalog (managed by [`server/src/services/catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/catalog-sync.ts)) to resolve model families or specific model IDs
2. **Provider Selection**: Uses a `switch (row.platform)` block to select the appropriate adapter (e.g., `openAiStyleEmbed`, `probeEmbeddingDimensions`)
3. **Credential Injection**: Retrieves API keys from the credential store defined in [`server/src/routes/keys.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts)
4. **Response Normalization**: Transforms vendor-specific responses into the standard OpenAI format with `object`, `data`, `embedding`, and `usage` fields

### Provider Adapters and Catalog System

FreeLLMAPI supports OpenAI, Google Gemini, NVIDIA, OpenRouter, Cloudflare, and HuggingFace through interchangeable adapter functions. The [`server/src/services/catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/catalog-sync.ts) module maintains a synchronized catalog of enabled embedding models, their dimensionalities, and priority rankings. When you specify `"model": "auto"`, the service selects the highest-priority model from the default embedding family.

## How to Generate Embeddings Using FreeLLMAPI

The following examples demonstrate practical implementations using the standard OpenAI-compatible interface.

### Making a Request with cURL

Send a simple HTTP POST to the embeddings endpoint using your FreeLLMAPI key:

```bash
curl -X POST https://api.freellmapi.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FREELLMAPI_KEY" \
  -d '{
        "model": "auto",
        "input": "Free LLMAPI makes embedding generation trivial."
      }'

```

The service returns a normalized JSON payload:

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.021, 0.113, -0.045, ...]
    }
  ],
  "model": "gemini-embedding-001",
  "usage": {
    "prompt_tokens": 3,
    "total_tokens": 3
  }
}

```

### Using the Node.js OpenAI Client

Because FreeLLMAPI maintains OpenAI compatibility, you can use the official `openai` package by simply changing the `baseURL`:

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FREELLMAPI_KEY,
  baseURL: "https://api.freellmapi.com/v1",
});

async function getEmbedding(text) {
  const response = await client.embeddings.create({
    model: "auto",
    input: text,
  });
  return response.data[0].embedding;
}

getEmbedding("Vector search with FreeLLMAPI")
  .then(vec => console.log(`Generated ${vec.length}-dimensional vector`))
  .catch(console.error);

```

### Python Implementation with Requests

For Python applications, use standard HTTP libraries to access the endpoint:

```python
import os
import requests

API_KEY = os.getenv("FREELLMAPI_KEY")
url = "https://api.freellmapi.com/v1/embeddings"

payload = {
    "model": "auto",
    "input": "FreeLLMAPI supports multiple embedding providers."
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
data = response.json()

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

```

### Targeting Specific Providers

To bypass automatic provider selection and target a specific model, pass the provider-specific model ID:

```bash
curl -X POST https://api.freellmapi.com/v1/embeddings \
  -H "Authorization: Bearer $FREELLMAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "text-embedding-3-large",
        "input": "Custom provider routing test"
      }'

```

Alternatively, use family names like `openai-embedding` or `gemini-embedding` to restrict routing to specific provider categories while still benefiting from fail-over within that family.

## Configuration and Provider Management

Understanding the configuration layer helps optimize embedding generation costs and performance characteristics.

### The Model Catalog ([`server/src/services/catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/catalog-sync.ts))

The catalog sync service maintains an up-to-date SQLite database of available models, including dimension counts, token limits, and provider priorities. The embeddings service queries this catalog during the model resolution phase to determine which provider adapter to invoke. You can configure default families through environment variables or the admin dashboard, which the `runEmbeddings` function references when processing `"model": "auto"` requests.

### Credential Management ([`server/src/routes/keys.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts))

API keys for each provider are stored securely through the keys route implementation in [`server/src/routes/keys.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts). The embeddings service retrieves the appropriate credential based on the selected provider platform during the adapter execution phase. Ensure you configure keys for each provider you intend to use via the dashboard under **Keys → Embedding** before making requests to non-default providers.

## Summary

- **FreeLLMAPI** provides an OpenAI-compatible `/embeddings` endpoint that unifies access to multiple AI providers through a single interface.
- The **`runEmbeddings`** function in [`server/src/services/embeddings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/embeddings.ts) handles model resolution, provider selection, and response normalization.
- Use **`"model": "auto"`** to leverage the default embedding family, or specify exact model IDs to target specific providers like OpenAI or Gemini.
- The system relies on **[`server/src/services/catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/catalog-sync.ts)** for model discovery and **[`server/src/routes/keys.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts)** for credential management.
- All providers return standardized responses containing the `embedding` array, `usage` statistics, and model identifiers.

## Frequently Asked Questions

### What embedding models are available through FreeLLMAPI?

FreeLLMAPI supports models from OpenAI (text-embedding-3-large, text-embedding-ada-002), Google Gemini (gemini-embedding-001), NVIDIA, HuggingFace, Cloudflare, and OpenRouter. The specific available models depend on which API keys you have configured in [`server/src/routes/keys.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts) and the current catalog synchronization state managed by [`server/src/services/catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/catalog-sync.ts).

### Does FreeLLMAPI support batch embedding generation?

Yes. The `input` parameter accepts either a single string or an array of strings. When providing an array, the service processes all inputs through the same provider and returns multiple embedding objects in the `data` array, each with a corresponding `index` field matching the input order.

### How does FreeLLMAPI handle provider failures?

The `runEmbeddings` function in [`server/src/services/embeddings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/embeddings.ts) implements fail-over logic within the provider selection block. If a primary provider returns an error or timeout, the service automatically attempts the next available provider in the same model family (if configured), ensuring high availability without requiring client-side retry logic.

### Can I use existing OpenAI client libraries with FreeLLMAPI?

Yes. Because the endpoint in [`server/src/routes/embeddings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/embeddings.ts) implements the complete OpenAI embeddings specification, you can use the official OpenAI Python or Node.js clients by changing only the `baseURL` to `https://api.freellmapi.com/v1` and providing your FreeLLMAPI key. All standard parameters including `encoding_format` and `dimensions` (where supported by the underlying provider) function identically.