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

# Model aliases

> Call a stable name, swap the model behind it — no redeploy, no code change.

An alias is a name **you** choose (`support-bot`) that points at a real model
(`Qwen/Qwen3-32B`). Your code calls the alias. When you want a different model
behind it, you repoint the alias, and your **next request** already routes
there. No deploy, no config change, nothing to ship.

This is what makes an [eval](/reference/evals) result *actionable*. An eval can
prove a cheaper model holds up on your traffic; without an alias, acting on that
means redeploying your application.

```bash theme={null}
# Your code, forever:
curl https://gateway.omnia-voice.com/v1/chat/completions \
  -H "Authorization: Bearer $OMNIA_API_KEY" \
  -d '{"model": "support-bot", "messages": [...]}'
```

## Create an alias

The **Models** page in the dashboard has an aliases manager (owner/admin):
create, repoint, and delete aliases, and configure the
[quality gate](#quality-gated-canaries) in the same dialog. Or from the API:

```bash theme={null}
curl -X PUT https://gateway.omnia-voice.com/v1/aliases \
  -H "Authorization: Bearer $OMNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "target_model": "Qwen/Qwen3-32B",
    "description": "our production support model"
  }'
```

Names are 3–64 characters (letters, numbers, dots, dashes, underscores) and
**scoped to your workspace**: your `support-bot` is yours alone. A name that
isn't an alias is treated as a normal model id, so aliases never shadow the
catalog.

## Repoint an alias

```bash theme={null}
curl -X PUT https://gateway.omnia-voice.com/v1/aliases \
  -H "Authorization: Bearer $OMNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "target_model": "Qwen/Qwen3-30B-A3B-Instruct-2507",
    "description": "switched after eval: 90% win rate, -88% cost"
  }'
```

That's it. Requests are routing to the new model within seconds, the same
request body, the same code, a different model. `PUT` is an upsert by name, so
CI can repoint idempotently without looking anything up first.

## Cut over gradually with a canary

Send a share of traffic to a candidate while the rest stays on the incumbent:

```json theme={null}
{
  "name": "support-bot",
  "target_model": "Qwen/Qwen3-32B",
  "canary_model": "Qwen/Qwen3-30B-A3B-Instruct-2507",
  "canary_percent": 10
}
```

10% of requests now serve the cheaper model. Watch it in
[Observability](/reference/observability), then raise the percentage, or set
`canary_percent: 0` to roll straight back. At `100` the cutover is complete and
you can make it the target.

<Note>
  The split is **per request**, not per user: a given caller may hit either model
  on consecutive requests. Sticky routing would require a user identifier we
  deliberately don't collect.
</Note>

## See which model served

Every response tells you:

```
X-Omnia-Alias: support-bot
X-Omnia-Served-Model: Qwen/Qwen3-30B-A3B-Instruct-2507
```

So a repoint or a canary split is never invisible: you can always see which
model answered, including on cache hits.

## Billing

**You are always billed for the model that ran**, at its normal rate. An alias
is a routing decision, never a pricing one: it doesn't add a fee, and it can't
disguise what a request cost.

## End-to-end example

```bash theme={null}
# 1. Prove the cheaper model holds up on your traffic
curl -X POST https://gateway.omnia-voice.com/v1/evals \
  -H "Authorization: Bearer $OMNIA_API_KEY" \
  -d '{"name":"can we drop to 30B?","rubric":"...",
       "baseline_model":"Qwen/Qwen3-32B",
       "candidate_models":["Qwen/Qwen3-30B-A3B-Instruct-2507"],
       "sample_count":200, "sample_filters":{"tag":"support-bot"}}'

# 2. It won, and the confidence interval is clear of 50%. Repoint.
curl -X PUT https://gateway.omnia-voice.com/v1/aliases \
  -H "Authorization: Bearer $OMNIA_API_KEY" \
  -d '{"name":"support-bot","target_model":"Qwen/Qwen3-30B-A3B-Instruct-2507"}'

# 3. Done. Your application code never changed.
```

## Quality-gated canaries

A canary split can supervise itself: pick a
[calibrated judge](/judges/calibration) (`gate_criterion_id`, a
criterion in the API) and the online scorer judges **both arms** of the live
split, promoting or rolling back on confidence-interval bounds. `recommend`
mode surfaces verdicts for you to act on; `auto` mode acts by itself, always
audited, and requires a judge at the **calibrated** tier (both TPR and TNR
≥ 90%): a weaker judge may recommend, but it cannot repoint traffic itself.

The whole gate is configurable **in the alias dialog on the Models page**,
judge, mode, minimum samples per arm, rollback threshold, and scoring window
not only via the API's `gate_*` fields. Every active gate and its latest
verdict is on the Evals page's **Live switches** tab. See
[Online monitoring](/judges/online-monitoring).

## Rules and limits

* **Owner/admin only** to create, repoint, or delete: repointing silently
  redirects live production traffic, so it's audited with the before/after.
* Every model in an alias is validated against the live catalog on save; a
  broken alias would fail every request that uses it.
* Deleting an alias makes requests using that name fail with "model not found".
  It's a real cutover step, not a cleanup.
* Aliases can't point at [dedicated endpoints](/dedicated/overview); a routing
  key already *is* a specific deployment.