> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnia-voice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The gateway

> How Omnia routes, meters, bills, and captures every request behind one endpoint.

The Omnia gateway is a single OpenAI-compatible endpoint that sits in front of
many models across multiple clouds. Your application never talks to a provider
directly; it talks to Omnia, and Omnia handles routing, metering, billing, and
(when you opt in) capture for the rest of the improvement workflow.

## One endpoint, every model

The base URL for all inference is:

```
https://gateway.omnia-voice.com/v1
```

You select a model by its id in the request body, and the id decides the route:

| `model` value                                                             | What it routes to                                                                                                               |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| A catalog id (`Qwen/Qwen3-32B`, ...)                                      | Shared per-token capacity. Unknown ids are `404`, never silently billed.                                                        |
| An [alias](/reference/model-aliases) (`support-bot`)                      | Whatever the alias points at today, including a canary split. Repoint the alias and the next request follows, with no redeploy. |
| `dedicated/<routing-key>`                                                 | Your [dedicated endpoint](/dedicated/overview), billed per GPU-hour instead of per token.                                       |
| A provider-prefixed id with [your own key](/reference/bring-your-own-key) | The closed provider you already use, on your key and their bill, while Omnia captures the traffic.                              |

Switching models is a one-string change: no new SDK, no new endpoint.

## OpenAI compatibility

Omnia implements the standard OpenAI request and response shapes:

* `POST /v1/chat/completions`: chat + vision
* `POST /v1/embeddings`: embeddings
* `POST /v1/responses`: the Responses API
* `POST /v1/rerank`: reranking
* `GET /v1/models`: the models you can call

Streaming, tool calls, and JSON mode behave the way your existing OpenAI code
expects, and unknown parameters are ignored rather than erroring. In most
cases, pointing your client at Omnia's base URL and swapping the key is the
only change you make.

## What happens on each request

<Steps>
  <Step title="Authenticate">
    Your API key resolves to a workspace. A missing or revoked key is rejected
    with `401`.
  </Step>

  <Step title="Resolve the route">
    Aliases resolve to their target (or canary arm), `dedicated/` prefixes to
    your endpoint, catalog ids to shared capacity.
  </Step>

  <Step title="Gate on balance">
    For per-token models, Omnia places a hold against your wallet sized to the
    request's worst-case cost. If your balance can't cover it, the request is
    refused with `402` before anything runs.
  </Step>

  <Step title="Serve from cache, if you opted in">
    With [response caching](/billing/caching) on, a byte-identical repeat
    within your retention window is served from the gateway's cache at 25% of
    the normal price. `X-Omnia-Cache: hit|miss` says what happened.
  </Step>

  <Step title="Route, infer, fall back">
    The request is forwarded to the model; streams relay token by token. If
    you passed [`fallbacks`](/inference/chat#fallback-models) (up to 2 backup
    models), the gateway retries them in order on upstream failure and reports
    which model actually answered.
  </Step>

  <Step title="Meter and settle">
    The exact tokens produced, including partial output on a cancelled
    stream, are metered and settled idempotently against the request id.
    Never billed twice, never billed for nothing.
  </Step>

  <Step title="Capture, if you opted in">
    With [request logging](/reference/request-logging) enabled, the exchange
    is secret-scrubbed and stored under your retention window, where grading,
    judges, evals, and datasets can reach it. Off by default; telemetry
    without it stays content-free.
  </Step>
</Steps>

## Label as you go

Two optional request headers thread through everything downstream, with no SDK
changes:

* `X-Omnia-Tag` names the task ("support", "extraction"). Tags become filters
  in logs, populations for [judges](/judges/calibration), and scopes for
  [datasets](/fine-tuning/datasets) and [evals](/reference/evals).
* `X-Omnia-Trace-Id` groups the steps of one agent run or conversation, so a
  multi-step run can be read, graded, and judged as a whole.

Untagged traffic still gets grouped automatically by
[segments](/concepts/segments).

## Two ways to run models

<CardGroup cols={2}>
  <Card title="Shared (per-token)" icon="layer-group">
    The default. Pooled capacity, billed per input/output token. Ideal for most
    workloads: no provisioning, pay only for what you use.
  </Card>

  <Card title="Dedicated (per-GPU-hour)" icon="server" href="/dedicated/overview">
    Private GPU capacity for a specific model, billed per GPU-hour while running.
    For guaranteed throughput, isolation, or serving your own fine-tuned models.
  </Card>
</CardGroup>

Being in the request path is what makes the gateway the richest of the four
[integration paths](/capture/overview): the same hop that routes and bills
also gives you caching, fallbacks, canary splits, and capture, with nothing
else to run.