Model names and aliases¶
A model id hard-coded in fifty apps is fifty pull requests every time a provider renames or retires it. In Vidai, apps call a name you choose. What that name means at the provider can change behind it, and every app follows without a deploy.
A model's names¶
| Name | What it is | Who sees it |
|---|---|---|
| The name apps call | The model's own name in Vidai, such as gpt-4.1-eu. It never changes |
Your apps, logs, cost, rules |
| Aliases | Other names apps can call the same model by, such as fast-model |
Your apps |
| Model id at the provider | What the provider's API calls it, such as gpt-4.1 or an Azure deployment name |
Only the provider |
Usually the name and the id at the provider are the same. When they differ, the gateway rewrites the model in the
request before it goes to the provider. In the Grachtwerk demo, apps call gpt-4.1-eu; the gateway sends gpt-4.1 to
the Azure deployment in West Europe.
flowchart LR
A["App asks for<br/>fast-model"] --> N["Vidai model<br/>gpt-4.1-mini-eu"]
N --> U["Provider is sent<br/>gpt-4.1-mini"]
What names give you¶
- Pin a version behind a stable name. Apps call one name while you choose exactly which version the provider serves.
- Vendor-neutral names. Call a model by what it's for (
fast-model,summariser). An alias can be removed from one model and given to another, so the name moves and the apps calling it follow. - Several names for one model, so apps written against older names keep working.

An alias is its model, everywhere¶
An alias is not a loophole. Everything set on a model applies to its aliases: whether a key may call it, routing rules that refuse or redirect it, switching it off, its fallback chains, its health at the gateway, its price. A key that may call a model may call its aliases; a key given only an alias doesn't get the model behind it.
What a program sees¶
GET /v1/models(andGET /v1beta/modelsfor Gemini SDKs) lists exactly what the key may call: each model, then its aliases, each alias naming its model.- The answer names the model that really served the call, and the gateway's
x-vidai-modelheader says the same; when that differs from what was asked,x-vidai-requested-modelgives the name the app sent. - Request logs record both: the name the app used, and the model that answered.
Names Vidai gives¶
When Find models brings in a provider's models, each gets its id as its name if that's free. If another provider
already uses the name, the new one is named after its provider, such as openai-eu/gpt-4o, and you can add an alias
of your choice.
Related¶
- Providers and models
- Model access
- Routing and fallback chains: send a name's calls to another model
- Translation between API formats