# How to Set Up OmniRoute's OpenAI-Compatible API Endpoint: A Complete Configuration Guide

> Configure OmniRoute's OpenAI-compatible API endpoint to route SDK clients through its LLM engine. Follow this complete guide for local setup and unified routing.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-14

---

**OmniRoute exposes a fully OpenAI-compatible HTTP API at `/v1/chat/completions` that you can run locally to route any OpenAI SDK client through its unified LLM routing engine.**

The **OmniRoute OpenAI-compatible API endpoint** lets developers replace direct OpenAI calls with a self-hosted proxy that automatically handles provider failover, request translation, and streaming. This guide walks through the setup process using the actual source implementation in `diegosouzapw/OmniRoute`.

## Architecture of the OpenAI-Compatible Endpoint

### Next.js API Route Structure

OmniRoute implements the public API as Next.js route handlers under `src/app/api/v1/`. The core chat completions endpoint lives in:

```

src/app/api/v1/chat/completions/route.ts

```

This file registers the `POST` handler that processes all OpenAI-format requests.

### Request Processing Pipeline

Each incoming request flows through five validated stages:

1. **CORS pre-flight** — Configured in [`src/shared/constants/cors.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/cors.ts) (allows any origin by default)
2. **Zod validation** — Enforces OpenAI schema compliance via [`src/open-sse/translator/request/openai-schema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/translator/request/openai-schema.ts)
3. **Authentication** — Optional API key check in [`src/server/authz/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/auth.ts)
4. **Policy enforcement** — Prompt injection guards and rate limits in [`open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/accountFallback.ts)
5. **Route to handler** — Delegation to [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)

### Translation and Execution Flow

After validation, [`chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/chatCore.ts) orchestrates the remaining pipeline:

- **Provider resolution** — Looks up target provider(s) in [`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts)
- **Request translation** — Converts OpenAI format to provider-native via [`open-sse/translator/request/openai-to-provider.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/request/openai-to-provider.ts)
- **Execution** — Calls the appropriate executor (e.g., [`open-sse/executors/openaiExecutor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/openaiExecutor.ts))
- **Response streaming** — Returns SSE chunks translated back to OpenAI format by [`open-sse/translator/response/openai-from-provider.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/response/openai-from-provider.ts)

The **Combo routing** system in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) provides automatic failover across providers with circuit-breaker protection.

## Step-by-Step Setup Instructions

### 1. Install and Configure the Server

```bash

# Clone and enter the repository

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute

# Install dependencies

npm install

# Copy environment template

cp .env.example .env

```

Edit `.env` to configure providers, API keys, and routing policies. The server uses port `20128` by default (defined in [`open-sse/config/constants.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/constants.ts)).

### 2. Start the Development Server

```bash
npm run dev

```

The **OmniRoute OpenAI-compatible API endpoint** is now available at:

```

http://localhost:20128/v1/chat/completions

```

### 3. Connect with the OpenAI SDK

```javascript
const { Configuration, OpenAIApi } = require("openai");

const configuration = new Configuration({
  apiKey: "any-string-works",           // OmniRoute validates in auth.ts
  basePath: "http://localhost:20128/v1" // Route to local OmniRoute
});

const client = new OpenAIApi(configuration);

async function chat() {
  const response = await client.createChatCompletion({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Hello, OmniRoute!" }],
    stream: true
  });

  // Handle SSE streaming
  response.data.on("data", data => {
    const chunk = data.choices?.[0]?.delta?.content;
    if (chunk) process.stdout.write(chunk);
  });
}

chat();

```

### 4. Test with cURL

```bash
curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-key" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "What is OmniRoute?"}],
    "temperature": 0.7
  }'

```

## Configuring Alternative Providers

To route requests to **Azure OpenAI** or other providers, register them in [`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts):

```typescript
// Example: Adding Azure OpenAI provider
registerProvider({
  name: "azure-gpt4",
  baseUrl: "https://my-resource.openai.azure.com/openai/deployments/gpt-4",
  auth: {
    type: "apiKey",
    header: "api-key",
    value: process.env.AZURE_API_KEY
  },
  targetFormat: "openai",
  models: ["gpt-4", "gpt-4-32k"]
});

```

When you request `"model": "gpt-4"`, OmniRoute automatically:
- Selects the Azure executor
- Translates the OpenAI payload to Azure's format
- Handles authentication headers
- Streams responses back in OpenAI-compatible chunks

## Key Configuration Files

| File | Purpose |
|------|---------|
| [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) | Main endpoint handler |
| [`src/open-sse/translator/request/openai-schema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/translator/request/openai-schema.ts) | OpenAI request validation |
| [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) | Core processing logic |
| [`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/providerRegistry.ts) | Provider-to-model mappings |
| [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) | Fallback and load balancing |
| [`open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/accountFallback.ts) | Circuit breaker and rate limits |
| [`open-sse/config/constants.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/constants.ts) | Timeouts, retries, defaults |

## Resilience Features

OmniRoute's **three-layer resilience system** ensures reliable API operation:

- **Provider circuit breaker** — Temporarily disables failing providers
- **Connection cooldown** — Prevents rapid reconnection to unstable endpoints
- **Model lockout** — Blocks specific model-provider combinations with repeated errors

These protections are implemented in [`accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/accountFallback.ts) and activate automatically without client-side changes.

## Summary

- **OmniRoute's OpenAI-compatible API endpoint** runs at `/v1/chat/completions` with full OpenAI SDK compatibility
- Setup requires `npm install`, environment configuration, and `npm run dev`
- The request pipeline in [`route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/route.ts) → [`chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/chatCore.ts) → executors handles validation, translation, and streaming
- Provider registration in [`providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/providerRegistry.ts) enables multi-provider routing with automatic failover
- Resilience features (circuit breaker, cooldown, combo routing) operate transparently

## Frequently Asked Questions

### Does OmniRoute support all OpenAI API features?

OmniRoute implements the core `/v1/chat/completions` endpoint with streaming support. Advanced features like function calling and vision depend on the underlying provider's capabilities and the translation layer in [`openai-to-provider.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/openai-to-provider.ts). Check [`openai-schema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/openai-schema.ts) for the exact payload validation rules.

### Can I use OmniRoute behind a reverse proxy?

Yes. The CORS configuration in [`src/shared/constants/cors.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/cors.ts) allows any origin by default. For production deployments, update [`constants.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/constants.ts) to restrict origins and configure your reverse proxy to forward requests to port `20128`.

### How does OmniRoute handle authentication?

Authentication is optional and implemented in [`src/server/authz/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/auth.ts). You can configure API key validation against your own database or disable it entirely for internal networks. The `Authorization: Bearer <key>` header format matches OpenAI's convention.