Complete Guide to OmniRoute API Endpoints: Chat, Embeddings, Audio, and Provider Management

OmniRoute exposes 30+ HTTP API endpoints under the /v1/ namespace, providing OpenAI-compatible chat completions, embeddings, audio synthesis, image generation, and provider management utilities, each implemented as Next.js App Router route handlers.

The diegosouzapw/OmniRoute repository implements a unified gateway for large language model providers. Every OmniRoute API endpoint follows a consistent architecture: CORS handling, Zod schema validation, optional authentication, and delegated business logic. Below is the complete reference to the available routes, their source locations, and usage patterns.

Chat Completions and Relay Architecture

OmniRoute provides two distinct paths for chat completions to support both public API consumers and internal routing logic.

/v1/chat/completions serves as the standard OpenAI-compatible entry point. The handler resides in src/app/api/v1/chat/completions/route.ts and accepts standard chat completion payloads with model selection and message arrays.

/v1/relay/chat/completions operates as the internal routing layer. Located at src/app/api/v1/relay/chat/completions/route.ts, this endpoint executes combo-logic, circuit-breaker checks, and provider failover before returning responses to the public API.

// Standard chat completion request
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: 'Explain OmniRoute architecture' }],
    temperature: 0.7
  })
});

Embeddings and Vector Operations

The platform exposes multiple endpoints for text and multimodal embeddings.

/v1/embeddings provides the primary OpenAI-compatible embedding interface, implemented in src/app/api/v1/embeddings/route.ts. It supports standard text-embedding models with batched inputs.

/v1/providers/<provider>/embeddings enables provider-specific embedding strategies, defined in src/app/api/v1/providers/[provider]/embeddings/route.ts. This allows direct access to native embedding formats from specific backends.

/v1/multimodal-embeddings supports cross-modal vectorization (text, image, or mixed inputs), located at src/app/api/v1/multimodal-embeddings/route.ts.

/v1/search and /v1/search/analytics handle vector search operations and usage analytics respectively.

// Generate embeddings for text
await fetch('https://your-omniroute-host/v1/embeddings', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'text-embedding-3-large',
    input: 'OmniRoute unifies many LLM providers.'
  })
});

Audio Processing Endpoints

OmniRoute supports full audio lifecycles including synthesis, transcription, and translation.

Text-to-Speech:

• /v1/audio/speech – Primary speech synthesis endpoint (src/app/api/v1/audio/speech/route.ts)
• /v1/voices – Catalog of available voice personas (src/app/api/v1/voices/route.ts)
• **/v1/text-to-speech/<voiceId>``** – Voice-specific synthesis endpoint (src/app/api/v1/text-to-speech/[voiceId]/route.ts`)

Speech-to-Text:

• /v1/audio/transcriptions – Standard transcription service (src/app/api/v1/audio/transcriptions/route.ts)
• /v1/audio/translations – Translation of audio to target languages (src/app/api/v1/audio/translations/route.ts)
• /v1/speech-to-text – General-purpose speech recognition endpoint (src/app/api/v1/speech-to-text/route.ts)

Multimodal Generation Services

Beyond text and audio, OmniRoute exposes endpoints for visual and musical content generation.

/v1/providers/<provider>/images/generations handles image creation through provider-specific pipelines (src/app/api/v1/providers/[provider]/images/generations/route.ts).

/v1/videos/generations enables video synthesis capabilities (src/app/api/v1/videos/generations/route.ts).

/v1/music/generations supports algorithmic music composition (src/app/api/v1/music/generations/route.ts).

/v1/ocr provides optical character recognition for document processing (src/app/api/v1/ocr/route.ts).

Provider Management and Model Discovery

These endpoints expose metadata about available providers and their capabilities.

/v1/models returns the aggregated model catalog across all configured providers (src/app/api/v1/models/route.ts). This powers provider selection dropdowns in client applications.

/v1/models/<model> retrieves detailed specifications for a specific model ID (src/app/api/v1/models/[...model]/route.ts).

/v1/providers lists all configured provider integrations (src/app/api/v1/providers/route.ts).

/v1/providers/<provider>/models and /v1/providers/<provider>/limits expose provider-specific model availability and quota/rate-limit configurations (src/app/api/v1/providers/[provider]/models/route.ts and src/app/api/v1/providers/[provider]/limits/route.ts).

/v1/providers/suggested-models offers curated model recommendations based on use case (src/app/api/v1/providers/suggested-models/route.ts).

// Retrieve complete model catalog
await fetch('https://your-omniroute-host/v1/models', {
  headers: { Accept: 'application/json' }
});

Administrative, Utility, and Safety Endpoints

API Key Management:

• /v1/registered-keys – List all registered API keys (src/app/api/v1/registered-keys/route.ts)
• /v1/registered-keys/<id> – Retrieve specific key metadata
• /v1/registered-keys/<id>/revoke – Revoke compromised or expired keys

Quota and Session Control:

• /v1/quotas/check – Real-time quota status verification (src/app/api/v1/quotas/check/route.ts)
• /v1/session-leases – Generate temporary API-key leases for ephemeral access (src/app/api/v1/session-leases/route.ts)

Content Safety and Analytics:

• /v1/moderations – Content safety classification (src/app/api/v1/moderations/route.ts)
• /v1/responses – Stream-compatible response format for complex chat flows (src/app/api/v1/responses/route.ts)
• /v1/rerank – Result re-ranking for retrieval-augmented generation (src/app/api/v1/rerank/route.ts)
• /v1/segment – Analytics event ingestion (src/app/api/v1/segment/route.ts)

User and System Status:

• /v1/me/status – Current user quota and permissions (src/app/api/v1/me/status/route.ts)
• /v1/management/proxy-subscriptions – Proxy subscription lifecycle management (src/app/api/v1/management/proxy-subscriptions/route.ts)

Catch-All and Error Handling

/v1/[...,omnirouteCatchAll] serves as the fallback handler for undefined paths (src/app/api/v1/[...omnirouteCatchAll]/route.ts). This endpoint returns standardized 404 responses for invalid routes, ensuring consistent error formatting across the OmniRoute API surface.

Summary

• OmniRoute organizes 30+ endpoints under the /v1/ namespace using Next.js App Router conventions.
• Core OpenAI compatibility is provided through chat/completions, embeddings, audio/speech, audio/transcriptions, and moderations endpoints.
• Provider-specific capabilities are namespaced under /v1/providers/<provider>/ for embeddings, images, models, and limits.
• Administrative functions include session leasing, registered key revocation, quota checks, and proxy subscription management.
• All routes implement a uniform middleware stack: CORS → Zod validation → optional auth → business logic handler.

Frequently Asked Questions

What is the base URL structure for OmniRoute API endpoints?

All OmniRoute API endpoints are prefixed with /v1/. For a deployment hosted at https://your-omniroute-host, the complete URL pattern follows https://your-omniroute-host/v1/{endpoint}. The relay layer and provider-specific routes extend this base path, such as /v1/relay/chat/completions or /v1/providers/openai/embeddings.

How does authentication work across these endpoints?

According to the source code in routes like src/app/api/v1/chat/completions/route.ts and src/app/api/v1/registered-keys/route.ts, authentication is optional at the middleware layer but enforced based on server configuration. Clients typically provide a Bearer token in the Authorization header. The session leasing endpoint (src/app/api/v1/session-leases/route.ts) generates temporary credentials specifically for short-lived access patterns.

What distinguishes the relay chat completions from the standard endpoint?

The standard /v1/chat/completions endpoint (src/app/api/v1/chat/completions/route.ts) provides direct OpenAI-compatible responses, while /v1/relay/chat/completions (src/app/api/v1/relay/chat/completions/route.ts) implements the internal routing intelligence. The relay handles circuit-breaker logic, provider combo-strategies, and failover mechanisms before returning final responses to the public API surface.

How can I programmatically check my quota limits?

Use the /v1/quotas/check endpoint defined in src/app/api/v1/quotas/check/route.ts. This endpoint accepts an API key identifier and returns current usage statistics, rate limits, and remaining quota. For provider-specific limits, query /v1/providers/<provider>/limits to retrieve backend-specific constraint information.

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