Model resolution

How the model field in a client request selects a registry — including auto for load balancing and smart routing — and how to filter models on the consumer in the UI.

A client never names a provider URL — it names a model (or uses auto), and TrustGate resolves which registry to use.

What clients send

Form	Example	Meaning
auto	"model": "auto"	Used when the consumer has load balancing (including smart routing). The gateway picks registry and model. Connect snippets show this automatically.
Short name	gpt-4o-mini	Sent as-is to the selected registry.
Provider-qualified	@openai/gpt-4o	Prefer registries of that provider, then pick.
Explicit model	any allowed model id	Required when multiple registries are bound without load balancing — the client must specify the model.

Copy the right form from the consumer Connect tab so snippets stay in sync with the strategy you configured.

Filter models on the consumer

Model restriction is configured on the consumer (or role), not as a Policies catalog plugin.

On the consumer Routing tab (or providers editor), for each registry row:

1. Leave all models permitted, or open Filter by available models and select a subset from that registry’s catalog.
2. Set the default model when the client omits model (must be in the filtered set when filtering is on).

A request for a model outside that registry’s filter is rejected during resolution, before it reaches the provider.

Roles can define the same per-registry allow-list and default; consumers that use the role inherit those model policies.

When load balancing is enabled, a member’s models list overrides the registry’s allowed list, and a member’s model pins the route outright. A member without model uses the policy default when that model is one of the member’s models, otherwise the first entry of models.

Resolution order

1. Read the model value (auto, short name, qualified, or empty → consumer/role default).
2. Narrow candidate registries from the consumer’s bindings (or smart-routing / LB pool).
3. Apply per-registry model filters — reject disallowed models; fill in the default when none was given.
4. Hand candidates to load balancing or smart routing, with fallback on failure when configured.

Related

• Consumers — Routing tab and Connect snippets
• Roles — shared model policies
• Load balancing · Smart routing
• Embeddings — candidate pool is embeddings-capable registries only
• Images — candidate pool is images-capable registries only; multipart model also pins
• Files — candidate pool is files-capable registries only
• Rerank — candidate pool is rerank-capable registries only
• Models — gateway-owned GET /v1/models, not a pin target