Complete Guide to FreeLLMAPI Endpoints: OpenAI-Compatible API Reference

FreeLLMAPI exposes eight primary REST endpoints under the /v1 namespace—including models, completions, chat, embeddings, audio, files, and fine-tunes—that mirror the OpenAI API contract and route requests to configurable LLM providers.

The tashfeenahmed/freellmapi repository provides a lightweight, self-hosted gateway that standardizes access to multiple large language model providers through a unified HTTP interface. By implementing the OpenAI REST specification, FreeLLMAPI endpoints allow developers to switch between GPT-4, Azure OpenAI, Mistral, or local models without modifying existing client code.

FreeLLMAPI Endpoint Overview

All routes are defined in server/src/router.ts and mounted under the /v1 path prefix. The following table maps each endpoint to its HTTP method, purpose, and source location:

Endpoint	Method	Description	Source Location
/v1/models	GET	Lists configured models	router.ts
/v1/completions	POST	Text completion requests	router.ts
/v1/chat/completions	POST	Chat completion requests	router.ts
/v1/embeddings	POST	Generate text embeddings	router.ts
/v1/audio/transcriptions	POST	Speech-to-text transcription	router.ts
/v1/audio/translations	POST	Audio translation to English	router.ts
/v1/files	GET/POST/DELETE	File upload and management	router.ts
/v1/fine-tunes	POST/GET/DELETE	Fine-tuning job management	router.ts

Detailed Endpoint Reference

List Models (GET /v1/models)

The models endpoint returns a JSON list of all LLMs configured in the server. The controller logic filters available providers based on the MODELS environment variable defined in server/src/env.ts.

Text Completions (POST /v1/completions)

Implemented in server/src/controllers/completions.ts, this endpoint accepts a prompt, model, and max_tokens parameter and returns generated text. It supports legacy completion formats compatible with OpenAI's text-davinci-003 style.

Chat Completions (POST /v1/chat/completions)

Located in server/src/controllers/chat.ts, this route handles conversational AI requests. It expects a messages array and routes the payload to the provider specified in the request or the default configured in env.ts.

Embeddings (POST /v1/embeddings)

The embeddings controller (server/src/controllers/embeddings.ts) generates vector representations for input text. It accepts input and model parameters, returning a list of floating-point vectors suitable for semantic search applications.

Audio Transcription and Translation (POST /v1/audio/*)

These endpoints in server/src/controllers/audio.ts provide OpenAI Whisper-compatible speech recognition. /v1/audio/transcriptions converts audio to text in the source language, while /v1/audio/translations converts audio to English text specifically.

File Management (/v1/files)

The files controller (server/src/controllers/files.ts) supports multipart form-data uploads for training datasets. It exposes GET for listing, POST for uploading, and DELETE for removing files used in fine-tuning workflows.

Fine-Tuning Jobs (/v1/fine-tunes)

This endpoint group manages custom model training. It accepts training file IDs uploaded via the files endpoint and monitors job status, with implementation details residing alongside the files controller in the router.

Authentication Flow

All FreeLLMAPI endpoints require Bearer token authentication. The middleware validates the Authorization: Bearer <API_KEY> header against the API_KEY value loaded from server/src/env.ts. Requests lacking valid credentials receive a 401 Unauthorized response before reaching any controller logic.

Key Implementation Files

Understanding the following source files helps when extending or debugging FreeLLMAPI endpoints:

• server/src/router.ts – Central Express router that registers all public /v1 routes and applies authentication middleware globally.
• server/src/controllers/completions.ts – Handles /v1/completions logic and provider-specific request formatting.
• server/src/controllers/chat.ts – Implements the chat completion protocol for conversational models.
• server/src/controllers/embeddings.ts – Manages vector embedding generation across configured providers.
• server/src/controllers/audio.ts – Processes audio uploads for transcription and translation tasks.
• server/src/controllers/files.ts – CRUD operations for file objects stored in the service.
• server/src/env.ts – Loads environment variables including provider API keys and the service's own authentication token.
• docs/api.md – Human-readable API documentation with full request/response schemas.

Integration Code Examples

The following JavaScript examples demonstrate how to call FreeLLMAPI endpoints using standard fetch. Configure BASE_URL and API_KEY to match your deployment.

const BASE_URL = 'https://your-freellmapi-instance.com/v1';
const API_KEY = 'sk-your-secret-key';  // From server/src/env.ts

// List available models
async function listModels() {
  const res = await fetch(`${BASE_URL}/models`, {
    headers: { Authorization: `Bearer ${API_KEY}` }
  });
  return res.json();
}

// Generate text completion
async function createCompletion(prompt) {
  const res = await fetch(`${BASE_URL}/completions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      model: 'gpt-3.5-turbo',
      prompt,
      max_tokens: 150
    })
  });
  return res.json();
}

// Chat completion
async function createChat(messages) {
  const res = await fetch(`${BASE_URL}/chat/completions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      model: 'gpt-3.5-turbo',
      messages
    })
  });
  return res.json();
}

// Generate embeddings
async function getEmbedding(input) {
  const res = await fetch(`${BASE_URL}/embeddings`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      model: 'text-embedding-ada-002',
      input
    })
  });
  return res.json();
}

// Transcribe audio (Whisper-compatible)
async function transcribeAudio(fileBlob) {
  const form = new FormData();
  form.append('file', fileBlob);
  form.append('model', 'whisper-1');

  const res = await fetch(`${BASE_URL}/audio/transcriptions`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}` },
    body: form
  });
  return res.json();
}

Summary

• FreeLLMAPI endpoints follow the OpenAI /v1 specification, enabling drop-in replacement for existing OpenAI clients.
• The service exposes eight endpoint groups covering models, text completions, chat, embeddings, audio processing, file management, and fine-tuning.
• Route definitions are centralized in server/src/router.ts, with business logic segregated into provider-agnostic controllers.
• All requests require Bearer token authentication validated against server/src/env.ts.
• The architecture supports routing to multiple backends including OpenAI, Azure OpenAI, and Mistral without client-side changes.

Frequently Asked Questions

Is FreeLLMAPI fully compatible with OpenAI's official API?

FreeLLMAPI implements the core OpenAI REST contract for completions, chat, embeddings, and audio, allowing most standard clients to connect by changing only the base URL and API key. Some provider-specific features may vary based on the underlying model's capabilities configured in server/src/env.ts.

How do I authenticate requests to FreeLLMAPI endpoints?

Every request must include an Authorization: Bearer <TOKEN> header. The service validates this token against the API_KEY environment variable defined in server/src/env.ts. Requests without valid credentials are rejected with a 401 status before reaching any controller.

Which LLM providers does FreeLLMAPI support?

According to the source code in server/src/env.ts and the controller logic, FreeLLMAPI can route requests to OpenAI, Azure OpenAI, Mistral, and other compatible endpoints. The specific provider for each request is determined by environment variables or the model parameter in the request body.

Can I use the official OpenAI Python or Node.js SDKs with FreeLLMAPI?

Yes. Because FreeLLMAPI endpoints mirror the OpenAI path structure and response formats, you can point the official SDKs to your instance by setting the baseURL (or api_base) to your FreeLLMAPI host and providing the custom API key from server/src/env.ts.

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