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

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 (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 on disk (lines 27-34 of 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 (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 (lines 1765-1783) accepts a PATCH request to update model settings.

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

Payload:

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

Python client example:

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 directly. The file structure maps model directory names to their settings objects:

{
  "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:

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:

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 by the ModelSettingsManager.
• Resolution: The EnginePool.resolve_model_id method in 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. According to the 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 (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 to remove the model_alias key from the specific model object and reload the configuration.

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