> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc.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).

<CodeGroup>
  ```bash Mac theme={null}
  export OPENROUTER_API_KEY=***
  ```

  ```bash Windows theme={null}
  setx OPENROUTER_API_KEY ***
  ```
</CodeGroup>

## Example

Install the `openai` package:

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

Use `OpenRouter` with your `Agent`:

<CodeGroup>
  ```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.")

  ```
</CodeGroup>

## 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](/reference/models/openai).

## Responses API

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

<CodeGroup>
  ```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")
  ```
</CodeGroup>

### 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](/reference/models/openrouter-responses) 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).