Skip to main content
Interact with OpenRouter models using the OpenAI Responses API. OpenRouter’s Responses API (currently in beta) provides OpenAI-compatible access to multiple AI models through a unified interface.

​
Requirements

Set the OPENROUTER_API_KEY environment variable: 
export OPENROUTER_API_KEY=your-api-key

​
Key Features

  • Unified Interface: Access multiple AI providers through a single API
  • Fallback Model Routing: Automatically try alternative models if the primary fails
  • Stateless API: Each request is independent (no server-side state persisted)
  • Reasoning Support: Enable reasoning for supported models

​
Parameters

ParameterTypeDefaultDescription
idstr"openai/gpt-oss-20b"The ID of the OpenRouter model to use
namestr"OpenRouterResponses"The name of the model
providerstr"OpenRouter"The provider of the model
api_keyOptional[str]NoneThe API key (defaults to OPENROUTER_API_KEY env var)
base_urlstr"https://openrouter.ai/api/v1"The base URL for the OpenRouter API
modelsOptional[List[str]]NoneList of fallback model IDs for automatic retry
storeOptional[bool]FalseWhether to store responses

​
Usage

​
Basic Usage

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")

​
With Reasoning

from agno.agent import Agent
from agno.models.openrouter import OpenRouterResponses

agent = Agent(
    model=OpenRouterResponses(
        id="openai/gpt-oss-20b",
        reasoning={"enabled": True},
    ),
    markdown=True,
)

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

​
Fallback Model Routing

If the primary model fails due to rate limits, timeouts, or unavailability, OpenRouter automatically tries the fallback models in order: 
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)

​
Developer Resources