Skip to main content
Models are the AI systems that process your requests. The AI Gateway supports flexible model naming and can route to the same model across different providers.

​
Specifying models

You can specify which model to use in your requests. The gateway supports several formats depending on how specific you need to be.

​
Just the model name

The simplest approach—use the model name directly: 
{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello"}]
}
The gateway looks up gpt-4o in the Model Catalog and automatically routes to the right provider (OpenAI in this case).

​
With a provider prefix

Use provider:model when you want to explicitly choose a provider: 
{
  "model": "anthropic:claude-3-5-sonnet-latest",
  "messages": [{"role": "user", "content": "Hello"}]
}
This is useful when:
  • A model name exists on multiple providers
  • You want to force a specific provider
  • You’re using a custom provider you’ve configured

​
With model author

Use the author/model format when you want to be specific about who authored the model: 
{
  "model": "anthropic/claude-sonnet-4",
  "messages": [{"role": "user", "content": "Hello"}]
}
The gateway will infer the provider from the model catalog. To also specify which provider should serve the model, add the provider prefix: 
{
  "model": "openrouter:anthropic/claude-sonnet-4",
  "messages": [{"role": "user", "content": "Hello"}]
}
This provider:author/model format lets you choose both the model author and which provider serves it. This is useful when the same model is available from multiple sources (like OpenRouter, Together, or a self-hosted instance).

​
Multiple models (fallback)

Specify multiple models for automatic fallback using the models array: 
{
  "model": "gpt-4o",
  "models": ["gpt-4o-mini", "claude-3-5-sonnet-20241022"],
  "messages": [{"role": "user", "content": "Hello"}]
}
The gateway tries models in order:
  1. model field first (primary choice)
  2. models array entries as fallbacks
You can use model alone, models alone, or both together—all are valid ways to specify client model preferences. This enables cross-provider failover—if OpenAI fails, the gateway can automatically try Anthropic.

​
Automatic model selection

Use the special ngrok/auto model to let the gateway choose based on your configured model selection strategy: 
{
  "model": "ngrok/auto",
  "messages": [{"role": "user", "content": "Hello"}]
}
This is equivalent to omitting the model field entirely. The gateway selects from available models based on your strategy (for example, lowest latency, lowest cost).

​
Unknown models (pass-through)

If a client requests a model that isn’t in the Model Catalog, the gateway can still route it if:
  1. The model name includes a provider prefix (for example, openai:some-new-model) or uses author syntax where the author is a known provider (for example, openai/some-new-model)
  2. The provider is known (either from the model catalog or a custom provider you’ve defined in your configuration) and allowed by your configuration
{
  "model": "openai:some-new-model",
  "messages": [{"role": "user", "content": "Hello"}]
}
The gateway extracts openai as the provider and forwards the request with some-new-model as the model name. This enables immediate access to new models before they’re added to the catalog.
Unknown models bypass catalog validation—the provider will return an error if the model doesn’t exist. Unknown models also lack metadata (pricing, capabilities) for model selection strategies.

​
Model aliases

The gateway automatically normalizes common model aliases. For example:
  • Shortened names may map to full version identifiers
  • Legacy names may map to current versions
You can also define custom aliases in your provider configuration: 
providers:
  - id: "openai"
    models:
      - id: "gpt-4o-2024-11-20"
        id_aliases: ["gpt-4o", "gpt-4-latest"]
Clients can then use any of these names to reach the same model.
Aliases must be unique across all models. You cannot use an alias that is already in use as an ID or alias by another model.

​
Model capabilities

Models have different capabilities that you can filter on using selection strategies:
  • Input modalities: text, image, audio, video, file
  • Output modalities: text, image, audio
  • Features: tool-calling, coding, vision, etc.
  • Context window: Maximum input tokens
  • Output tokens: Maximum output tokens
See the Model Catalog for capabilities of each model.

​
Next steps