Complete Guide to OmniRoute API Endpoints: The Full /v1/ Reference

OmniRoute exposes a comprehensive HTTP API under the /v1/ namespace, implementing OpenAI-compatible chat, embeddings, audio, and image endpoints alongside provider management utilities in Next.js App Router files.

The diegosouzapw/OmniRoute repository implements a unified gateway for large language models and multimodal services. Every endpoint follows a consistent architecture defined in route.ts files located throughout the src/app/api/v1/ directory, processing requests through CORS handling, Zod validation, optional authentication, and delegated business logic handlers.

Core OpenAI-Compatible Endpoints

OmniRoute mirrors the standard OpenAI API surface to ensure drop-in compatibility with existing clients and SDKs.

Chat Completions

The primary inference endpoint resides at /v1/chat/completions, implemented in src/app/api/v1/chat/completions/route.ts. This handler accepts standard chat completion payloads and routes them to configured upstream providers.

A separate internal relay exists at /v1/relay/chat/completions (src/app/api/v1/relay/chat/completions/route.ts). This performs intelligent routing logic, combo-model execution, and circuit-breaker checks before delegating to the public completion handler.

Embeddings

Text embeddings are available at /v1/embeddings (src/app/api/v1/embeddings/route.ts), supporting standard OpenAI embedding formats. Provider-specific embedding implementations reside under /v1/providers/<provider>/embeddings (src/app/api/v1/providers/[provider]/embeddings/route.ts), allowing direct access to vendor-native capabilities.

Audio Processing

OmniRoute provides three primary audio endpoints:

• Speech synthesis: /v1/audio/speech (src/app/api/v1/audio/speech/route.ts) converts text to speech
• Transcription: /v1/audio/transcriptions (src/app/api/v1/audio/transcriptions/route.ts) handles speech-to-text
• Translation: /v1/audio/translations (src/app/api/v1/audio/translations/route.ts) translates spoken audio to text

Additional voice management is available through /v1/voices (src/app/api/v1/voices/route.ts) for catalog retrieval and /v1/text-to-speech/<voiceId> (src/app/api/v1/text-to-speech/[voiceId]/route.ts) for voice-specific synthesis. A general-purpose speech-to-text endpoint exists at /v1/speech-to-text (src/app/api/v1/speech-to-text/route.ts).

Vision and Media Generation

Image generation is exposed under /v1/providers/<provider>/images/generations (src/app/api/v1/providers/[provider]/images/generations/route.ts), routing to provider-specific implementations. Video generation resides at /v1/videos/generations (src/app/api/v1/videos/generations/route.ts), while music generation is available at /v1/music/generations (src/app/api/v1/music/generations/route.ts).

Moderations and Safety

Content safety checks are implemented at /v1/moderations (src/app/api/v1/moderations/route.ts), providing content classification and policy violation detection compatible with OpenAI's moderation API.

Provider Management and Discovery

OmniRoute exposes detailed provider introspection endpoints that expose available models, quotas, and capabilities.

Model Catalogs

The global model list is accessible at /v1/models (src/app/api/v1/models/route.ts), returning aggregated available models across all configured providers. Individual model details are retrieved via /v1/models/<model> (src/app/api/v1/models/[...model]/route.ts). Provider-specific model listings reside at /v1/providers/<provider>/models (src/app/api/v1/providers/[provider]/models/route.ts).

Provider Configuration

The root provider list is available at /v1/providers (src/app/api/v1/providers/route.ts). Provider-specific limits and quotas are exposed at /v1/providers/<provider>/limits (src/app/api/v1/providers/[provider]/limits/route.ts). Suggested model configurations are available at /v1/providers/suggested-models (src/app/api/v1/providers/suggested-models/route.ts).

Advanced and Utility Endpoints

Beyond OpenAI compatibility, OmniRoute implements several specialized endpoints for enterprise deployments.

Session and Key Management

Temporary API key leasing is handled by /v1/session-leases (src/app/api/v1/session-leases/route.ts). Persistent key management operates through /v1/registered-keys (src/app/api/v1/registered-keys/route.ts), supporting listing, individual key retrieval (/v1/registered-keys/<id>), and revocation (/v1/registered-keys/<id>/revoke). Quota verification is available at /v1/quotas/check (src/app/api/v1/quotas/check/route.ts).

Specialized AI Services

• Responses API: /v1/responses (src/app/api/v1/responses/route.ts) implements a streaming-compatible response format for real-time applications
• Reranking: /v1/rerank (src/app/api/v1/rerank/route.ts) performs result re-ranking for search and retrieval applications
• Multimodal embeddings: /v1/multimodal-embeddings (src/app/api/v1/multimodal-embeddings/route.ts) handles image-text combined embeddings
• OCR: /v1/ocr (src/app/api/v1/ocr/route.ts) provides optical character recognition capabilities
• Search: /v1/search (src/app/api/v1/search/route.ts) and /v1/search/analytics (src/app/api/v1/search/analytics/route.ts) provide vector/keyword search and analytics

Message and User Management

Message history is accessible at /v1/messages (src/app/api/v1/messages/route.ts), with token counting available at /v1/messages/count_tokens (src/app/api/v1/messages/count_tokens/route.ts). Current user status is retrieved via /v1/me/status (src/app/api/v1/me/status/route.ts).

Management and Plugin Infrastructure

Proxy subscription management is handled under /v1/management/proxy-subscriptions (src/app/api/v1/management/proxy-subscriptions/route.ts) with refresh capabilities. The provider plugin manifest is exposed at /v1/provider-plugin-manifest (src/app/api/v1/provider-plugin-manifest/route.ts). Analytics events are captured at /v1/segment (src/app/api/v1/segment/route.ts).

Catch-All Route

Unknown paths are handled by /v1/[...omnirouteCatchAll] (src/app/api/v1/[...omnirouteCatchAll]/route.ts), which returns appropriate 404 responses.

Implementation Architecture

Every endpoint follows a standardized pipeline defined in its respective route.ts file: CORS headers are applied first, followed by Zod schema validation, optional authentication checks, and finally delegation to business logic handlers. This pattern ensures consistent error handling, type safety, and cross-origin compatibility across the entire surface area.

Code Examples

Calling Chat Completions

// POST /v1/chat/completions
const response = await fetch('https://your-omniroute-host/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.OMNIROUTE_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Hello, world!' }],
    stream: false,
  }),
});

const completion = await response.json();

Retrieving Available Models

// GET /v1/models
const models = await fetch('https://your-omniroute-host/v1/models', {
  headers: { 
    'Accept': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
}).then(r => r.json());

Generating Embeddings

// POST /v1/embeddings
const embedding = await fetch('https://your-omniroute-host/v1/embeddings', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.OMNIROUTE_API_KEY}`
  },
  body: JSON.stringify({
    model: 'text-embedding-3-large',
    input: 'OmniRoute unifies many LLM providers.',
  }),
});

Summary

• OmniRoute implements the full OpenAI-compatible API surface under /v1/, including chat completions, embeddings, audio processing, and moderations.
• Provider-specific capabilities are namespaced under /v1/providers/<provider>/, exposing granular control over models, limits, and media generation.
• Enterprise utilities include session leasing (/v1/session-leases), quota checking (/v1/quotas/check), and registered key management (/v1/registered-keys).
• Every endpoint is implemented as a Next.js App Router route.ts file following the pattern: CORS → Zod validation → optional auth → handler.
• The Responses API (/v1/responses) and Rerank (/v1/rerank) endpoints extend functionality beyond standard OpenAI compatibility.

Frequently Asked Questions

What is the base URL structure for OmniRoute API endpoints?

All OmniRoute API endpoints are prefixed with /v1/ relative to your host domain (e.g., https://api.yourdomain.com/v1/). The implementation uses Next.js App Router file-based routing, with each endpoint defined in src/app/api/v1/[endpoint]/route.ts files.

How does authentication work across OmniRoute endpoints?

According to the source code in src/app/api/v1/chat/completions/route.ts and other handlers, endpoints support optional authentication via Bearer tokens in the Authorization header. The session leasing endpoint (/v1/session-leases) and registered keys management (/v1/registered-keys) provide mechanisms for temporary and persistent API key administration.

What is the difference between /v1/chat/completions and /v1/relay/chat/completions?

While /v1/chat/completions (src/app/api/v1/chat/completions/route.ts) provides the standard public API, /v1/relay/chat/completions (src/app/api/v1/relay/chat/completions/route.ts) implements the internal routing layer. The relay performs intelligent provider selection, combo-model logic, and circuit-breaker checks before delegating to the public completion handler.

How can I check my quota limits before making expensive API calls?

Use the /v1/quotas/check endpoint (src/app/api/v1/quotas/check/route.ts) to verify available quota for a given API key before initiating resource-intensive operations like video generation or large embedding batches. For provider-specific limits, query /v1/providers/<provider>/limits (src/app/api/v1/providers/[provider]/limits/route.ts).

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