> ## Documentation Index
> Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Fallbacks

> Automatic failover between models

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.

## How it works

Provide an array of model IDs in priority order. If the first model returns an error, OpenRouter will automatically try the next model in the list.

```typescript title="TypeScript SDK" lines theme={null}
import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const response = await openRouter.responses.send({
  responsesRequest: {
    models: ['~anthropic/claude-sonnet-latest', 'gryphe/mythomax-l2-13b'],
    input: 'What is the meaning of life?',
  },
});

if (!('output' in response)) {
  throw new Error('Expected a non-streaming response');
}

const message = [...response.output].reverse().find((item) => item.type === 'message');
console.log(message?.content.find((part) => part.type === 'output_text')?.text);
```

```typescript title="TypeScript (fetch)" lines theme={null}
const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    models: ['~anthropic/claude-sonnet-latest', 'gryphe/mythomax-l2-13b'],
    input: 'What is the meaning of life?',
  }),
});

type ResponseOutputItem = {
  type: string;
  content?: { type: string; text?: string }[];
};

const data: { output: ResponseOutputItem[] } = await response.json();
const message = [...data.output].reverse().find((item) => item.type === 'message');
console.log(message?.content?.find((part) => part.type === 'output_text')?.text);
```

```python title="Python" expandable lines theme={null}
import requests
import json

response = requests.post(
  url="https://openrouter.ai/api/v1/responses",
  headers={
    "Authorization": "Bearer <OPENROUTER_API_KEY>",
    "Content-Type": "application/json",
  },
  data=json.dumps({
    "models": ["~anthropic/claude-sonnet-latest", "gryphe/mythomax-l2-13b"],
    "input": "What is the meaning of life?"
  })
)

data = response.json()
message = next(item for item in reversed(data['output']) if item['type'] == 'message')
print(next(part['text'] for part in message['content'] if part['type'] == 'output_text'))
```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"models": []string{"~anthropic/claude-sonnet-latest", "gryphe/mythomax-l2-13b"},
		"input":  "What is the meaning of life?",
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("request failed: %s", resp.Status)
	}

	var result struct {
		Output []struct {
			Type    string `json:"type"`
			Content []struct {
				Type string `json:"type"`
				Text string `json:"text"`
			} `json:"content"`
		} `json:"output"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}

	for i := len(result.Output) - 1; i >= 0; i-- {
		if result.Output[i].Type != "message" {
			continue
		}
		for _, part := range result.Output[i].Content {
			if part.Type == "output_text" {
				fmt.Println(part.Text)
				return
			}
		}
		return
	}
}

```

```bash title="cURL" lines theme={null}
curl -s https://openrouter.ai/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
    "models": ["~anthropic/claude-sonnet-latest", "gryphe/mythomax-l2-13b"],
    "input": "What is the meaning of life?"
  }' | jq -r '[.output[] | select(.type == "message")] | last | .content[] | select(.type == "output_text") | .text'

```

```text title="Output" theme={null}
There's no single agreed-upon answer, but here are the main ways people have approached it.

**Major perspectives**
- **Religious/spiritual:** Meaning comes from a source beyond us, such as serving God, achieving enlightenment, or fulfilling a divine purpose.
- **Existentialist:** Life has no built-in meaning, so we create our own through our choices and commitments (Sartre, Camus). Camus added that we can live fully even while accepting the universe's silence.
- **Humanist/ethical:** Meaning comes from human flourishing: caring for others, reducing suffering, and building a better world.
- **Aristotelian:** The point is to live well, developing your capacities and virtues over a whole life (*eudaimonia*).
- **Naturalistic/scientific:** Life evolved without a purpose, but that doesn't stop us from finding things worthwhile. Purpose can be real to us without being cosmic.
- **Absurdist/humorous:** Douglas Adams said 42. Not entirely a joke, since it points out that we may be asking the wrong question.

**What the research suggests**
Psychologists who study meaning tend to find the same ingredients:
- Close relationships and belonging
- Work or projects that feel significant
- A sense of coherence, that your life makes sense as a story
- Connection to something larger than yourself, whether community, nature, or a cause

**A way to think about it**
"What is *the* meaning of life?" may be less useful than "What makes *my* life feel meaningful?" The first assumes one answer for everyone. The second is something you can explore, test, and revise.

Are you asking out of curiosity, or is this something you're wrestling with personally? I'm happy to go deeper either way.
```

## Fallback behavior

If the model you selected returns an error, OpenRouter will try to use the fallback model instead. If the fallback model is down or returns an error, OpenRouter will return that error.

By default, any error can trigger the use of a fallback model, including:

* Context length validation errors
* Moderation flags for filtered models
* Rate-limiting
* Downtime

## Pricing

Requests are priced using the model that was ultimately used, which will be returned in the `model` attribute of the response body.

This applies to [`:free` models](https://openrouter.ai/docs/guides/routing/model-variants/free) too. If a `:free` model is followed by a paid model in `models` and OpenRouter falls back to the paid model, you're billed at the paid model's price. To keep a request free, list only `:free` models.

## Using with the Anthropic Messages API

The Anthropic Messages API endpoint (`/api/v1/messages`) accepts the `fallbacks` parameter, matching the shape used by Anthropic's SDKs. Each entry names a fallback model to try in order, and the list maps to OpenRouter's `models` routing, so fallbacks trigger on the same errors listed above (rate limits, downtime, moderation refusals), not only on refusals.

> [!NOTE]
>
> OpenRouter handles this fallback routing itself. The `fallbacks` parameter does not use Anthropic's server-side fallback feature.

```typescript lines theme={null}
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  baseURL: 'https://openrouter.ai/api',
  apiKey: '<OPENROUTER_API_KEY>',
});

const message = await anthropic.beta.messages.create({
  model: 'anthropic/claude-sonnet-4.5',
  max_tokens: 1024,
  fallbacks: [{ model: 'anthropic/claude-opus-4.1' }],
  messages: [{ role: 'user', content: 'What is the meaning of life?' }],
});

for (const block of message.content) {
  if (block.type === 'text') {
    console.log(block.text);
  }
}

```

```python title="Python" lines theme={null}
import os

import anthropic

client = anthropic.Anthropic(
    base_url="https://openrouter.ai/api",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

message = client.beta.messages.create(
    model="anthropic/claude-sonnet-4.5",
    max_tokens=1024,
    extra_body={"fallbacks": [{"model": "anthropic/claude-opus-4.1"}]},
    messages=[{"role": "user", "content": "What is the meaning of life?"}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model":      "anthropic/claude-sonnet-4.5",
		"max_tokens": 1024,
		"fallbacks":  []map[string]string{{"model": "anthropic/claude-opus-4.1"}},
		"messages": []map[string]string{
			{"role": "user", "content": "What is the meaning of life?"},
		},
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/messages", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("anthropic-version", "2023-06-01")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("request failed: %s", resp.Status)
	}

	var message struct {
		Content []struct {
			Type string `json:"type"`
			Text string `json:"text"`
		} `json:"content"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&message); err != nil {
		log.Fatal(err)
	}

	for _, block := range message.Content {
		if block.Type == "text" {
			fmt.Println(block.Text)
		}
	}
}

```

```bash title="cURL" lines theme={null}
curl -s https://openrouter.ai/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "max_tokens": 1024,
    "fallbacks": [{ "model": "anthropic/claude-opus-4.1" }],
    "messages": [{ "role": "user", "content": "What is the meaning of life?" }]
  }' | jq -r '.content[] | select(.type == "text") | .text'

```

```text title="Output" theme={null}
The meaning of life is one of humanity's oldest questions, and there's no single answer. Here are some common perspectives:

**Philosophical views:**
- Creating your own meaning through choices and actions (existentialism)
- Pursuing happiness, virtue, or knowledge
- Connecting with something greater than yourself

**Religious perspectives:**
- Serving or connecting with God/the divine
- Preparing for an afterlife
- Following spiritual teachings and principles

**Secular approaches:**
- Building relationships and loving others
- Reducing suffering and increasing wellbeing
- Learning, growing, and experiencing life
- Contributing to society or leaving a legacy
- Finding purpose through work, creativity, or passion

**Biological view:**
- Survival and reproduction (though humans often seek meaning beyond this)

Many people find meaning through a combination of these—connection with others, personal growth, contributing to something meaningful, and experiencing joy and beauty.

What resonates most with you? The question itself can be as valuable as any answer, prompting reflection on what makes *your* life feel worthwhile.
```

### Limitations

* Each `fallbacks` entry accepts only the `model` field. Per-attempt overrides such as `max_tokens`, `thinking`, `speed`, or `output_config` are rejected with a 400 error.
* `fallbacks` cannot be combined with the `models` parameter; sending both returns a 400 error.
* `fallbacks` accepts at most 3 entries; longer lists return a 400 error.

## Using with the OpenAI SDK

To use the `models` array with the OpenAI SDK, include it in the `extra_body` parameter. In the example below, `~openai/gpt-sol-latest` will be tried first, and the `models` array will be tried in order as fallbacks.

```python Python expandable lines theme={null}
from openai import OpenAI

openai_client = OpenAI(
  base_url="https://openrouter.ai/api/v1",
  api_key="<OPENROUTER_API_KEY>",
)

response = openai_client.responses.create(
    model="~openai/gpt-sol-latest",
    extra_body={
        "models": ["~anthropic/claude-sonnet-latest", "gryphe/mythomax-l2-13b"],
    },
    input="What is the meaning of life?"
)

print(response.output_text)
```

```typescript TypeScript expandable lines theme={null}
import OpenAI from 'openai';

const openrouterClient = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: '<OPENROUTER_API_KEY>',
});

async function main() {
  const response = await openrouterClient.responses.create({
    model: '~openai/gpt-sol-latest',
    // @ts-expect-error
    models: ['~anthropic/claude-sonnet-latest', 'gryphe/mythomax-l2-13b'],
    input: 'What is the meaning of life?',
  });
  console.log(response.output_text);
}

main();
```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model":  "~openai/gpt-sol-latest",
		"models": []string{"~anthropic/claude-sonnet-latest", "gryphe/mythomax-l2-13b"},
		"input":  "What is the meaning of life?",
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("request failed: %s", resp.Status)
	}

	var result struct {
		Output []struct {
			Type    string `json:"type"`
			Content []struct {
				Type string `json:"type"`
				Text string `json:"text"`
			} `json:"content"`
		} `json:"output"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}

	for _, item := range result.Output {
		if item.Type != "message" {
			continue
		}
		for _, part := range item.Content {
			if part.Type == "output_text" {
				fmt.Print(part.Text)
			}
		}
	}
	fmt.Println()
}

```

```bash title="cURL" lines theme={null}
curl -s https://openrouter.ai/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
    "model": "~openai/gpt-sol-latest",
    "models": ["~anthropic/claude-sonnet-latest", "gryphe/mythomax-l2-13b"],
    "input": "What is the meaning of life?"
  }' | jq -r '[.output[] | select(.type == "message")] | last | .content[] | select(.type == "output_text") | .text'

```

```text title="Output" theme={null}
There may be no single meaning of life, but that doesn’t mean life is meaningless.

Some people understand meaning as a purpose they’re given by God or a spiritual tradition. Others think we create it through our choices. And often, meaning feels less like something we invent or discover than something that grows: a friendship deepens, a skill becomes a vocation, or someone comes to count on us.

A practical answer is to pay attention to what you find worth caring for, even when it’s hard. You don’t need an answer for your whole life to know what matters today.
```
