OpenRouter

OpenRouter is a platform providing endpoints for Large Language Models.

Authentication

Set your OPENROUTER_API_KEY environment variable. Get your key from here.

export OPENROUTER_API_KEY=***

setx OPENROUTER_API_KEY ***

Example

Install the openai package:

uv pip install -U agno openai

Use OpenRouter with your Agent:

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.

Responses API

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

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:

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 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.

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

Authentication

Example

Params

Responses API

Fallback Model Routing

Prompt caching

​Authentication

​Example

​Params

​Responses API

​Fallback Model Routing

​Prompt caching

Authentication

Example

Params

Responses API

Fallback Model Routing

Prompt caching