> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenRouter

> Use OpenRouter unified API with Agno agents.

OpenRouter is a platform providing endpoints for Large Language Models.

## Authentication

Set your `OPENROUTER_API_KEY` environment variable. Get your key from [here](https://openrouter.ai/settings/keys).

```bash Mac theme={null}
export OPENROUTER_API_KEY=***
```

```bash Windows theme={null}
setx OPENROUTER_API_KEY ***
```

## Example

Install the `openai` package:

```shell theme={null}
uv pip install -U agno openai
```

Use `OpenRouter` with your `Agent`:

```python agent.py theme={null}
from agno.agent import Agent
from agno.models.openrouter import OpenRouter

agent = Agent(
    model=OpenRouter(id="openai/gpt-5-mini"),
    markdown=True
)

# Print the response in the terminal
agent.print_response("Share a 2 sentence horror story.")

```

## Params

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | `str` | `"gpt-5.4-mini"` | The id of the OpenRouter model to use |
| `name` | `str` | `"OpenRouter"` | The name of the model |
| `provider` | `str` | `"OpenRouter"` | The provider of the model |
| `api_key` | `Optional[str]` | `None` | The API key for OpenRouter (defaults to OPENROUTER\_API\_KEY env var) |
| `base_url` | `str` | `"https://openrouter.ai/api/v1"` | The base URL for the OpenRouter API |
| `max_tokens` | `int` | `1024` | The maximum number of tokens to generate |
| `models` | `Optional[List[str]]` | `None` | Fallback model IDs tried in order if the primary model fails |

`OpenRouter` also supports the params of [OpenAI](https://agno-v2.mintlify.site/reference/models/openai.md).

## Responses API

OpenRouter also supports the OpenAI Responses API (currently in beta). Use `OpenRouterResponses` for this interface:

```python agent.py theme={null}
from agno.agent import Agent
from agno.models.openrouter import OpenRouterResponses

agent = Agent(
    model=OpenRouterResponses(id="openai/gpt-oss-20b"),
    markdown=True,
)

agent.print_response("Share a 2 sentence horror story")
```

### Fallback Model Routing

`OpenRouterResponses` supports automatic fallback to alternative models if the primary model fails:

```python theme={null}
from agno.agent import Agent
from agno.models.openrouter import OpenRouterResponses

agent = Agent(
    model=OpenRouterResponses(
        id="openai/gpt-oss-20b",
        models=["openai/gpt-oss-20b", "openai/gpt-4o"],
    ),
    markdown=True,
)

agent.print_response("Write a haiku about coding", stream=True)
```

See [OpenRouterResponses reference](https://agno-v2.mintlify.site/reference/models/openrouter-responses.md) for full parameters.

## Prompt caching

Prompt caching happens automatically with the `OpenRouter` model when the underlying provider supports it. For other providers, enable it by setting the `cache_control` field in the request body.
You can read more about prompt caching with OpenRouter in [their docs](https://openrouter.ai/docs/features/prompt-caching).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.