How to Integrate OmniRoute with Existing Node.js Projects

OmniRoute is a self-hosted OpenAI-compatible proxy that runs on localhost:20128, allowing any Node.js application to route AI requests through multiple providers using standard HTTP clients or the official OpenAI SDK without code changes beyond the endpoint URL.

OmniRoute provides a self-hosted proxy/router that exposes a single OpenAI-compatible HTTP API, making it trivial to integrate with existing Node.js codebases. Because it mimics the OpenAI API contract exactly, you can point any standard HTTP client—or the official openai SDK—at your local OmniRoute instance and immediately gain access to 340+ providers with automatic failover and token compression.

Quick Start: Running OmniRoute Locally

Integration requires only two steps: install the CLI globally and start the server.

npm i -g omniroute
npx omniroute

By default, the server listens on http://localhost:20128. Once running, any Node.js process can send requests to http://localhost:20128/v1/chat/completions. No SDK installation is required in your project.

Integration Methods for Node.js

Because OmniRoute exposes an OpenAI-compatible interface, you can integrate it using any HTTP library or the official SDK. Below are three common approaches.

Using Axios (Non-Streaming)

The simplest approach uses any HTTP client like Axios. This example from [examples/quickstart/nodejs_axios.js](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/examples/quickstart/nodejs_axios.js) demonstrates a standard POST request:

const axios = require('axios');

const API_URL = 'http://localhost:20128/v1/chat/completions';
const headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer dummy-key', // Any string works for free providers
};

const data = {
  model: 'felo/auto',      // Key-less free backend
  stream: false,
  messages: [{ role: 'user', content: 'Hello! What can you do?' }],
};

axios.post(API_URL, data, { headers })
  .then(res => console.log(res.data.choices[0].message.content))
  .catch(err => {
    console.error('Error:', err.message);
    if (err.response) console.error('Server replied:', err.response.data);
  });

Note: The Authorization header is required by the API contract but accepts any dummy value when using zero-config free providers.

Using Native Fetch with Streaming (SSE)

Node.js 22+ includes global fetch, enabling Server-Sent Events (SSE) streaming without external dependencies:

const API_URL = 'http://localhost:20128/v1/chat/completions';
const body = {
  model: 'auto',
  stream: true,
  messages: [{ role: 'user', content: 'Explain the difference between promises and callbacks.' }],
};

fetch(API_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer dummy-key',
    'Accept': 'text/event-stream',
  },
  body: JSON.stringify(body),
})
  .then(res => {
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    
    async function read() {
      const { value, done } = await reader.read();
      if (done) return;
      process.stdout.write(decoder.decode(value));
      await read();
    }
    return read();
  })
  .catch(console.error);

The server routes streaming requests through the early-keepalive wrapper defined in [src/app/api/v1/chat/completions/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/v1/chat/completions/route.ts), ensuring clients receive standard OpenAI SSE events.

Using the Official OpenAI SDK

For existing projects already using the OpenAI SDK, integration requires only changing the baseURL:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:20128/v1', // Point to OmniRoute
  apiKey: 'dummy-key',                  // Required but unused for free backends
});

const chat = await client.chat.completions.create({
  model: 'auto/coding', // Quality-first combo for code generation
  messages: [{ role: 'user', content: 'Write a quick sort in JavaScript.' }],
});

console.log(chat.choices[0].message.content);

The SDK sends a standard POST /v1/chat/completions request, which OmniRoute processes through the same route implementation used by raw HTTP clients.

How Requests Are Processed Internally

When your Node.js code hits http://localhost:20128/v1/chat/completions, OmniRoute executes a multi-stage pipeline defined in the source code:

1. Request Validation: The payload is validated against a Zod schema in [src/app/api/v1/chat/completions/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/v1/chat/completions/route.ts), ensuring OpenAI API compatibility.
2. Guardrails: Prompt-injection detection, admission-queue logic, and optional compression headers are applied immediately.
3. Translation: The initTranslators function in [open-sse/translator/index.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/translator/index.ts) converts OpenAI-style payloads to the internal routing format.
4. Routing: The Auto-Combo engine selects the optimal provider based on quota, latency, and cost constraints, leveraging strategies defined in [src/sse/handlers/chat.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/sse/handlers/chat.ts).
5. Resilience: Circuit breakers ([src/open-sse/services/circuitBreaker.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/open-sse/services/circuitBreaker.ts)) and account-level cooldowns ([src/open-sse/services/accountFallback.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/open-sse/services/accountFallback.ts)) prevent cascading failures.
6. Response: The result streams back as SSE or JSON, matching the OpenAI spec exactly.

Features You Gain Automatically

By routing through OmniRoute instead of calling providers directly, existing Node.js projects instantly benefit from:

• Zero-Config Free Providers: Use model: "felo/auto" without API keys.
• Automatic Fallback: Access to 341 providers across 19 routing strategies.
• Token Compression: RTK and Caveman compression algorithms reduce token counts by 15-95%.
• Built-in Guardrails: Prompt-injection detection, rate-limit handling, and circuit breakers operate transparently.

Summary

• OmniRoute exposes an OpenAI-compatible API at localhost:20128, requiring no SDK changes in your Node.js project.
• Three integration methods work out of the box: raw HTTP (Axios/fetch), native Node.js fetch with streaming, and the official OpenAI SDK via baseURL configuration.
• Internal routing occurs through [src/app/api/v1/chat/completions/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/v1/chat/completions/route.ts) and [open-sse/translator/index.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/translator/index.ts), providing automatic failover and compression.
• Installation requires only npm i -g omniroute and npx omniroute to begin accepting requests.

Frequently Asked Questions

Do I need to modify my existing OpenAI SDK code to use OmniRoute?

No. You only need to change the baseURL to http://localhost:20128/v1 and provide any dummy API key. All existing method calls like client.chat.completions.create() function identically because OmniRoute mirrors the OpenAI API contract exactly, including SSE streaming formats.

What Node.js versions support the streaming fetch example?

The native streaming example requires Node.js 22 or higher, which includes global fetch and ReadableStream support. For older versions, use the Axios example or install the node-fetch package. Both approaches work with OmniRoute's standard HTTP interface.

How does authentication work when using free providers?

OmniRoute accepts any string in the Authorization header (e.g., Bearer dummy-key) when routing to free providers. The [src/app/api/v1/chat/completions/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/v1/chat/completions/route.ts) implementation validates the header format but ignores the token value for key-less backends like felo/auto.

Can I integrate OmniRoute into a production Node.js application?

Yes. The [src/open-sse/services/circuitBreaker.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/open-sse/services/circuitBreaker.ts) and [src/open-sse/services/accountFallback.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/open-sse/services/accountFallback.ts) services provide production-grade resilience through provider-level circuit breakers and automatic cooldowns for rate-limited accounts. Run OmniRoute as a persistent service or container alongside your Node.js application.

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