# How to Set Up Model Aliases for Custom API-Visible Names in oMLX

> Learn how to set up model aliases in oMLX to use custom API-visible names. Decouple storage layout from client identifiers for better API management.

- Repository: [Jun Kim/omlx](https://github.com/jundot/omlx)
- Tags: how-to-guide
- Published: 2026-05-11

---

**oMLX lets you define a human-friendly `model_alias` in per-model settings that appears in API responses instead of the model’s directory name, decoupling storage layout from client-facing identifiers.**

oMLX is an open-source inference engine that supports custom model aliases, allowing you to expose user-friendly names like "gpt-4-lite" while keeping technical directory names like "qwen3.5-35b" in the filesystem. This article explains how to configure and resolve model aliases using the internal `ModelSettings` dataclass, the admin API, and the resolution engine.

## How Model Aliases Work in oMLX

The alias system relies on three core components that bridge storage and API visibility:

- **`ModelSettings`** — A dataclass defined in [`omlx/model_settings.py`](https://github.com/jundot/omlx/blob/main/omlx/model_settings.py) (lines 50-54) that stores per-model configuration. The field `model_alias: Optional[str]` holds the custom API-visible name.

- **`ModelSettingsManager`** — Persists `ModelSettings` instances to [`model_settings.json`](https://github.com/jundot/omlx/blob/main/model_settings.json) on disk (lines 27-34 of [`omlx/model_settings.py`](https://github.com/jundot/omlx/blob/main/omlx/model_settings.py)). When you save an alias, this manager writes it to the JSON configuration.

- **`EnginePool.resolve_model_id`** — The resolver located in [`omlx/engine_pool.py`](https://github.com/jundot/omlx/blob/main/omlx/engine_pool.py) (lines 60-96) that maps incoming model names to actual directory IDs. It checks aliases after exact matches and case-insensitive matches but before applying provider prefixes.

When a request arrives at endpoints like `POST /v1/chat/completions`, the server calls `resolve_model_id`. If the requested name matches an alias stored in `ModelSettings`, the function returns the underlying model directory ID, transparently routing the request while displaying the alias in server info and UI listings.

## Setting Up a Model Alias

### Via the Admin API

The admin endpoint implemented in [`omlx/admin/routes.py`](https://github.com/jundot/omlx/blob/main/omlx/admin/routes.py) (lines 1765-1783) accepts a `PATCH` request to update model settings.

**Endpoint:** `PATCH /admin/api/model-settings/{model_id}`

**Payload:**

```json
{
  "model_alias": "gpt-4-lite"
}

```

**Python client example:**

```python
import requests

base_url = "https://your-omlx-instance"
model_id = "qwen3.5-35b"
url = f"{base_url}/admin/api/model-settings/{model_id}"

payload = {"model_alias": "gpt-4-lite"}
headers = {"Authorization": f"Bearer {YOUR_API_KEY}"}

response = requests.patch(url, json=payload, headers=headers)
print(response.status_code)  # 200 if successful

```

To remove an alias, send `"model_alias": null` in the same payload.

### Via Manual Configuration

You can edit [`model_settings.json`](https://github.com/jundot/omlx/blob/main/model_settings.json) directly. The file structure maps model directory names to their settings objects:

```json
{
  "version": 1,
  "models": {
    "qwen3.5-35b": {
      "model_alias": "gpt-4-lite",
      "max_context_window": 8192,
      "temperature": 0.7
    }
  }
}

```

Save the file and restart the oMLX server or trigger a settings reload to apply changes.

## Verifying Alias Resolution

You can programmatically verify that an alias resolves to the correct model ID using the internal resolver classes:

```python
from pathlib import Path
from omlx.engine_pool import EnginePool
from omlx.model_settings import ModelSettingsManager

# Initialize components

pool = EnginePool(Path("./models"))
settings_mgr = ModelSettingsManager(Path("./"))

# Test resolution

alias = "gpt-4-lite"
real_id = pool.resolve_model_id(alias, settings_mgr)
print(f"Alias '{alias}' resolves to directory '{real_id}'")

# Output: Alias 'gpt-4-lite' resolves to directory 'qwen3.5-35b'

```

This invokes the same `resolve_model_id` logic used by the REST API, confirming that your alias configuration is active before client integration.

## Using Aliases in Client Requests

Once configured, clients can use the alias in any request that accepts a model parameter:

```bash
curl -X POST https://your-omlx-instance/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OMLX_API_KEY" \
  -d '{
    "model": "gpt-4-lite",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

```

The server transparently maps "gpt-4-lite" to the underlying "qwen3.5-35b" directory via the `EnginePool` resolver while returning the alias in response metadata.

## Summary

- **Storage:** Aliases are defined in the `model_alias` field of the `ModelSettings` dataclass and persisted to [`model_settings.json`](https://github.com/jundot/omlx/blob/main/model_settings.json) by the `ModelSettingsManager`.
- **Resolution:** The `EnginePool.resolve_model_id` method in [`omlx/engine_pool.py`](https://github.com/jundot/omlx/blob/main/omlx/engine_pool.py) automatically translates aliases to directory names during request processing.
- **Configuration:** Set aliases via the `PATCH /admin/api/model-settings/{model_id}` endpoint or by directly editing the JSON configuration file.
- **Usage:** Clients use aliases in API calls exactly like standard model IDs; resolution happens server-side without client modifications.

## Frequently Asked Questions

### Where is the model alias stored?

The alias is stored in the per-model `model_alias` field within [`model_settings.json`](https://github.com/jundot/omlx/blob/main/model_settings.json). According to the [`omlx/model_settings.py`](https://github.com/jundot/omlx/blob/main/omlx/model_settings.py) source code, this field is defined as `Optional[str]` in the `ModelSettings` dataclass (lines 50-54) and persisted by the `ModelSettingsManager` (lines 27-34).

### Can multiple models share the same alias?

No. The `resolve_model_id` method in [`omlx/engine_pool.py`](https://github.com/jundot/omlx/blob/main/omlx/engine_pool.py) (lines 60-96) performs a lookup that assumes unique mappings. If multiple models define the same alias, the resolver will return the first match it encounters during iteration, leading to non-deterministic routing.

### Do aliases support provider prefixes like "omlx/"?

Provider prefixes are handled separately from alias resolution. The `resolve_model_id` function checks for aliases before stripping provider prefixes such as `omlx/`. This means you can reference an alias with or without a prefix, but the prefix is not part of the alias definition itself.

### How do I remove an alias without deleting the model?

Send a `PATCH` request to `/admin/api/model-settings/{model_id}` with `"model_alias": null` in the JSON body. Alternatively, manually edit [`model_settings.json`](https://github.com/jundot/omlx/blob/main/model_settings.json) to remove the `model_alias` key from the specific model object and reload the configuration.