OpenRouter provides two options for model routing: Auto Router for intelligent model selection and the models parameter for automatic fallback handling.
Auto Router
The Auto Router, a special model ID that you can use to choose between selected high-quality models based on your prompt, powered by NotDiamond.
The Auto Router analyzes your prompt and automatically selects the best model from a curated list of high-quality models. The selected model will be returned in the response's model attribute.
Usage Examples
import { OpenRouter } from '@openrouter/sdk';
const openRouter = new OpenRouter({
apiKey: '<OPENROUTER_API_KEY>',
});
const completion = await openRouter.chat.send({
model: 'openrouter/auto',
messages: [
{
role: 'user',
content: 'What is the meaning of life?',
},
],
});
console.log(completion.choices[0].message.content);
const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'openrouter/auto',
messages: [
{
role: 'user',
content: 'What is the meaning of life?',
},
],
}),
});
const data = await response.json();
console.log(data.choices[0].message.content);
import requests
import json
response = requests.post(
url="https://openrouter.ai/api/v1/chat/completions",
headers={
"Authorization": "Bearer <OPENROUTER_API_KEY>",
"Content-Type": "application/json",
},
data=json.dumps({
"model": "openrouter/auto",
"messages": [
{
"role": "user",
"content": "What is the meaning of life?"
}
]
})
)
data = response.json()
print(data['choices'][0]['message']['content'])
Response Model Information
The resulting generation will have model set to the model that was actually used. This allows you to see which model the Auto Router selected for your specific prompt.
The models Parameter
The models parameter lets you automatically try other models if the primary model's providers are down, rate-limited, or refuse to reply due to content moderation.
OpenRouter will automatically try models in order until one succeeds. Fallbacks are triggered for:
- Provider downtime or errors
- Rate limiting
- Content moderation refusals
- Context length validation errors
Note: If all models in the array fail, OpenRouter will return the error from the last attempted model.
Usage Examples
import { OpenRouter } from '@openrouter/sdk';
const openRouter = new OpenRouter({
apiKey: '<OPENROUTER_API_KEY>',
});
const completion = await openRouter.chat.send({
models: ['anthropic/claude-3.5-sonnet', 'gryphe/mythomax-l2-13b'],
messages: [
{
role: 'user',
content: 'What is the meaning of life?',
},
],
});
console.log(completion.choices[0].message.content);
const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer <OPENROUTER_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
models: ['anthropic/claude-3.5-sonnet', 'gryphe/mythomax-l2-13b'],
messages: [
{
role: 'user',
content: 'What is the meaning of life?',
},
],
}),
});
const data = await response.json();
console.log(data.choices[0].message.content);
import requests
import json
response = requests.post(
url="https://openrouter.ai/api/v1/chat/completions",
headers={
"Authorization": "Bearer <OPENROUTER_API_KEY>",
"Content-Type": "application/json",
},
data=json.dumps({
"models": ["anthropic/claude-3.5-sonnet", "gryphe/mythomax-l2-13b"],
"messages": [
{
"role": "user",
"content": "What is the meaning of life?"
}
]
})
)
data = response.json()
print(data['choices'][0]['message']['content'])
Pricing
Requests are priced using the model that was ultimately used, which will be returned in the model attribute of the response body. You only pay for the model that successfully processed your request.
Using with OpenAI SDK
To use the models array with the OpenAI SDK, include it in the extra_body parameter. In the example below, gpt-4o will be tried first, and the models array will be tried in order as fallbacks.
from openai import OpenAI
openai_client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key="<OPENROUTER_API_KEY>",
)
completion = openai_client.chat.completions.create(
model="openai/gpt-4o",
extra_body={
"models": ["anthropic/claude-3.5-sonnet", "gryphe/mythomax-l2-13b"],
},
messages=[
{
"role": "user",
"content": "What is the meaning of life?"
}
]
)
print(completion.choices[0].message.content)
import OpenAI from 'openai';
const openrouterClient = new OpenAI({
baseURL: 'https://openrouter.ai/api/v1',
apiKey: '<OPENROUTER_API_KEY>',
});
async function main() {
// @ts-expect-error
const completion = await openrouterClient.chat.completions.create({
model: 'openai/gpt-4o',
models: ['anthropic/claude-3.5-sonnet', 'gryphe/mythomax-l2-13b'],
messages: [
{
role: 'user',
content: 'What is the meaning of life?',
},
],
});
console.log(completion.choices[0].message);
}
main();
- The primary model (specified in
model) is tried first - Fallback models in the
modelsarray are tried in order - Only the first successful model's response is returned
- Pricing is based on the model that successfully handled the request
- When using OpenAI SDK with TypeScript, you may need to use
@ts-expect-errorsincemodelsis not part of the standard OpenAI types
Best Practices
When to Use Each Option
- Auto Router: Use when you want OpenRouter to intelligently select the best model based on your prompt. Best for general-purpose applications.
- Models Parameter: Use when you have specific model preferences and want explicit fallback behavior. Best for production applications requiring reliability.
- Order fallback models by your preference and cost considerations
- Use Auto Router for experimentation to discover which models work best for your use case
- Monitor the
modelfield in responses to track which models are actually being used - Consider cost differences when setting up fallback chains