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

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 (allows any origin by default)
2. Zod validation — Enforces OpenAI schema compliance via src/open-sse/translator/request/openai-schema.ts
3. Authentication — Optional API key check in src/server/authz/auth.ts
4. Policy enforcement — Prompt injection guards and rate limits in open-sse/services/accountFallback.ts
5. Route to handler — Delegation to open-sse/handlers/chatCore.ts

Translation and Execution Flow

After validation, chatCore.ts orchestrates the remaining pipeline:

• Provider resolution — Looks up target provider(s) in open-sse/config/providerRegistry.ts
• Request translation — Converts OpenAI format to provider-native via open-sse/translator/request/openai-to-provider.ts
• Execution — Calls the appropriate executor (e.g., open-sse/executors/openaiExecutor.ts)
• Response streaming — Returns SSE chunks translated back to OpenAI format by open-sse/translator/response/openai-from-provider.ts

The Combo routing system in 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

# 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).

2. Start the Development Server

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

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

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:

// 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	Main endpoint handler
src/open-sse/translator/request/openai-schema.ts	OpenAI request validation
open-sse/handlers/chatCore.ts	Core processing logic
open-sse/config/providerRegistry.ts	Provider-to-model mappings
open-sse/services/combo.ts	Fallback and load balancing
open-sse/services/accountFallback.ts	Circuit breaker and rate limits
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 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 → chatCore.ts → executors handles validation, translation, and streaming
• Provider registration in 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. Check 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 allows any origin by default. For production deployments, update 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. 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.

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