How to Generate Embeddings Using FreeLLMAPI: Complete API Guide

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)

The entry point for all embedding requests resides in 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)

The runEmbeddings function in 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) 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
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 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:

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:

{
  "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:

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:

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:

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)

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)

API keys for each provider are stored securely through the keys route implementation in 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 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 for model discovery and 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 and the current catalog synchronization state managed by 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}