Models

Models are the AI systems that process your requests. You specify the model in each request body, and you can use an access key configuration to restrict which models an access key may call.

Specifying models

Model name only

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello"}]
}

The gateway looks up gpt-4o in the model catalog and routes to OpenAI. If OpenAI fails, it can try other providers that serve the same model. The full catalog ID, author/model such as openai/gpt-4o, works the same way.

Provider prefix

{
  "model": "anthropic:claude-sonnet-4-6",
  "messages": [{"role": "user", "content": "Hello"}]
}

Use provider:model when you want to force a specific provider or target a model you run yourself.

Multiple models (failover)

List fallback models with the models array:

{
  "model": "gpt-4o",
  "models": ["gpt-4o-mini", "anthropic:claude-sonnet-4-6"],
  "messages": [{"role": "user", "content": "Hello"}]
}

The gateway tries model first, then each entry in models in order, until one succeeds.

Virtual models

A virtual model is a name you save in your account, such as chat-default, that stands for an ordered list of models. Send the name as model, and the gateway tries the models in order:

{
  "model": "chat-default",
  "messages": [{"role": "user", "content": "Hello"}]
}

Use one to change the models your apps use from the gateway, without changing their code or requests. It also gives failover to a client that can’t send a models array. See Virtual models.

Unknown models (pass-through)

If a model isn’t in the catalog, the gateway still routes it when you include a provider prefix:

{
  "model": "openai:some-new-model",
  "messages": [{"role": "user", "content": "Hello"}]
}

The provider returns an error if the model doesn’t exist. The access key’s configuration must still allow pass-through models.

Model and provider names

Model names aren’t case-sensitive: gpt-4o, GPT-4o, and Gpt-4O all resolve to the same model. The gateway matches provider names exactly, so use the lowercase Provider ID from the model catalog. Name models and providers by their primary catalog ID. The gateway doesn’t resolve alternate names for either.

Model capabilities

Models differ in input/output modalities, context window, and features. See the model catalog for details.

Next steps

Model catalog: Supported models by provider
Choose a model: Model IDs and provider prefixes
Configure fallback models: Try another model when the first one fails
Restrict providers and models: Limit models per key

Concepts

Getting Started With

SDKs

Agents

Guides

Observability

Examples

Reference

API Reference

Specifying models

Model name only

Provider prefix

Multiple models (failover)

Virtual models

Unknown models (pass-through)

Model and provider names

Model capabilities

Next steps

​Specifying models

​Model name only

​Provider prefix

​Multiple models (failover)

​Virtual models

​Unknown models (pass-through)

​Model and provider names

​Model capabilities

​Next steps

Specifying models

Model name only

Provider prefix

Multiple models (failover)

Virtual models

Unknown models (pass-through)

Model and provider names

Model capabilities

Next steps