The AI Gateway includes default model mapping that handles equivalencies between models from different providers. This enables seamless switching, load balancing, and fallback scenarios without changing your application code.

The gateway ships with comprehensive default mappings that work out-of-the-box, but you can override them for your specific needs.

​
Getting Started

​
What is Model Mapping?

Model mapping defines equivalencies between models from different providers, enabling the gateway to automatically substitute similar models when:

  • Load balancing across providers with different model names
  • Provider fallback when your preferred provider is unavailable
  • Cost optimization by routing to cheaper equivalent models
  • Performance tuning by selecting faster equivalent models

For complete configuration options and syntax, see the Configuration Reference.

​
How Model Mapping Works

The gateway uses a 3-tier mapping system with automatic fallback. When load balancing routes a request to a different provider, the system checks for model equivalencies in this order:

1

Direct Support

First, check if the target provider offers the requested model directly.

If you request gpt-4o and load balancing routes to OpenAI, no mapping needed - OpenAI supports gpt-4o natively.

# No mapping needed - direct support
User requests: gpt-4o → Load balancer routes to OpenAI → Uses gpt-4o
2

Router-Specific Mapping

Next, check for custom mappings defined in your specific router configuration.

These override both direct support and global defaults, giving you fine-grained control per router.

routers:
  production:
    model-mappings:
      gpt-4o: 
        - claude-3-opus    # Custom mapping for this router

# Result: gpt-4o request → Routes to Anthropic → Uses claude-3-opus
3

Global Default Mapping

Check organization-wide default mappings you’ve configured.

These apply to all routers unless overridden by router-specific mappings.

default-model-mapping:
  gpt-4o: 
    - claude-3-5-sonnet   # Global preference

# Result: gpt-4o request → Routes to Anthropic → Uses claude-3-5-sonnet
4

Built-in Default Mapping

Finally, fall back to the gateway’s built-in default mappings.

These are comprehensive defaults that ship with the gateway and cover all major models and providers.

# Built-in mapping (from embedded configuration)
gpt-4o: 
  - claude-3-5-sonnet
  - gemini-1.5-pro

# Result: gpt-4o request → Routes to Anthropic → Uses claude-3-5-sonnet

​
Configuration Examples

The gateway ships with comprehensive default mappings that prioritize equivalent quality and capability. You only need custom mappings when you want to override these defaults for your specific use case.

Use case: You believe different models are more equivalent than the defaults suggest.

routers:
  custom-equivalents:
    model-mappings:
      # Default maps gpt-4o to claude-3-5-sonnet
      # But you think claude-3-opus is more equivalent for your use case
      gpt-4o: 
        - claude-3-opus
      
      # Default maps claude-3-5-sonnet to gpt-4o
      # But you think gemini-1.5-pro is more equivalent
      claude-3-5-sonnet: 
        - gemini-1.5-pro
    
    load-balance:
      chat:
        strategy: latency
        providers:
          - openai
          - anthropic
          - gemini

What happens: When load balancer routes a gpt-4o request to Anthropic, it uses claude-3-opus instead of the default claude-3-5-sonnet mapping.

For complete configuration options and syntax, see the Configuration Reference.

​
Coming Soon

The following model mapping features are planned for future releases:

FeatureDescriptionVersion
Intelligent MappingAutomatically maintained model equivalencies that update with new model releases, eliminating the need for manual configurationv2