Skip to main content

🏷ī¸ Model Aliasing

Use aliases to map a single model name to different actual models across providers. This lets you hot-switch between backends on the fly — no restart, no code changes.

📋 Scenario​

Your app always requests gpt-4o. You want to be able to switch between:

  • OpenAI's actual GPT-4o (direct routing, no transform)
  • Anthropic's Claude Sonnet (with format conversion via a rule)

⚙ī¸ Setup​

🏷ī¸ Define the Alias Group​

aliases:
  - input_model_id: gpt-4o
    options:
      - id: alias-gpt4o-openai
        downstream_id: openai
        output_model_id: gpt-4o       # Active by default (first in list)

      - id: alias-gpt4o-anthropic
        downstream_id: anthropic
        output_model_id: claude-sonnet-4-20250514

📏 Define Routing Rules (Optional)​

rules:
  # When routed to Anthropic from OpenAI format, convert
  - id: chat-anthropic
    name: Chat Completions -> Anthropic
    pattern_path: /v1/chat/completions
    match_format: [openai]
    match_downstream_format: [anthropic]
    match_downstreams: [anthropic]
    pipeline_config:
      - plugin_id: openai2anthropic
    is_enabled: true

Note: Since the Anthropic downstream declares api_formats: [anthropic], auto-translation would handle format conversion automatically. The explicit rule above is shown to demonstrate format-filtered rules.

⚡ Hot-Switching​

🔄 Switch to Claude Sonnet​

./tresor alias activate alias-gpt4o-anthropic

Now requests for gpt-4o are forwarded to Anthropic as claude-sonnet-4. Auto-translation applies openai2anthropic on the request side and converts responses back.

↩ī¸ Switch Back to OpenAI

./tresor alias activate alias-gpt4o-openai

Requests for gpt-4o go directly to OpenAI as gpt-4o (no transformation needed since both sides use the same format).

🔍 How It Works​

The model resolution hierarchy ensures the right behavior:

  1. Alias check first — Tresor looks for an active alias for gpt-4o
  2. If alias points to OpenAI → direct forward (same format, no transform needed)
  3. If alias points to Anthropic → auto-translation inserts openai2anthropic transform (and any matching rules contribute their pipelines)
  4. The model name in the request body is rewritten to the alias's output_model_id

This means you can add more options to the group as new providers or models become available:

  - input_model_id: gpt-4o
    options:
      - id: alias-gpt4o-openai
        downstream_id: openai
        output_model_id: gpt-4o

      - id: alias-gpt4o-sonnet
        downstream_id: anthropic
        output_model_id: claude-sonnet-4-20250514

      - id: alias-gpt4o-opus
        downstream_id: anthropic
        output_model_id: claude-opus-4-20250514

And switch between any of them with a single CLI command or web UI click.

đŸŽ¯ Regex Aliases: Match a Family of Models​

Regex aliases let you map all models matching a pattern to a single output. This is useful when you want to normalize a family of model variants through one backend.

Example: Route all Claude models to Anthropic Sonnet

aliases:
  - input_model_id: "^claude-.*"
    options:
      - id: alias-claude-to-sonnet
        downstream_id: anthropic
        output_model_id: claude-sonnet-4-20250514
        is_regex: true

Now any request for claude-sonnet-4, claude-opus-4, or claude-haiku-4.5 will be forwarded to Anthropic as claude-sonnet-4-20250514. This is useful for A/B testing or forcing all Claude variants through a single model for cost control.

Priority rule: Exact-match aliases always take precedence over regex aliases. If you have an exact alias for claude-sonnet and a regex alias ^claude-.*, a request for claude-sonnet will use the exact match.

Model discovery: Regex aliases are excluded from the /v1/models endpoint since they represent patterns, not concrete model IDs.

Creating regex aliases: Use the web UI's "Regex" checkbox when creating or editing alias groups. The CLI does not have a --regex flag; for CLI usage, create the alias through the web UI or admin API (POST /api/aliases with is_regex: true).