# Complete Guide to FreeLLMAPI Endpoints: OpenAI-Compatible API Reference

> Explore FreeLLMAPI endpoints for OpenAI-compatible API access. Discover models, completions, chat, embeddings, audio, files, and fine-tunes. Integrate with ease.

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

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/router.ts) |
| `/v1/completions` | POST | Text completion requests | [router.ts](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/router.ts) |
| `/v1/chat/completions` | POST | Chat completion requests | [router.ts](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/router.ts) |
| `/v1/embeddings` | POST | Generate text embeddings | [router.ts](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/router.ts) |
| `/v1/audio/transcriptions` | POST | Speech-to-text transcription | [router.ts](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/router.ts) |
| `/v1/audio/translations` | POST | Audio translation to English | [router.ts](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/router.ts) |
| `/v1/files` | GET/POST/DELETE | File upload and management | [router.ts](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/router.ts) |
| `/v1/fine-tunes` | POST/GET/DELETE | Fine-tuning job management | [router.ts](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/env.ts).

### Text Completions (`POST /v1/completions`)

Implemented in [`server/src/controllers/completions.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/env.ts).

### Embeddings (`POST /v1/embeddings`)

The embeddings controller ([`server/src/controllers/embeddings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/router.ts)** – Central Express router that registers all public `/v1` routes and applies authentication middleware globally.
- **[`server/src/controllers/completions.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/controllers/completions.ts)** – Handles `/v1/completions` logic and provider-specific request formatting.
- **[`server/src/controllers/chat.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/controllers/chat.ts)** – Implements the chat completion protocol for conversational models.
- **[`server/src/controllers/embeddings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/controllers/embeddings.ts)** – Manages vector embedding generation across configured providers.
- **[`server/src/controllers/audio.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/controllers/audio.ts)** – Processes audio uploads for transcription and translation tasks.
- **[`server/src/controllers/files.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/controllers/files.ts)** – CRUD operations for file objects stored in the service.
- **[`server/src/env.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/env.ts)** – Loads environment variables including provider API keys and the service's own authentication token.
- **[`docs/api.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.

```javascript
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/router.ts), with business logic segregated into provider-agnostic controllers.
- All requests require Bearer token authentication validated against [`server/src/env.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/env.ts).