feat(models): add native OpenRouter model class

Author: abhishekbhakat

docs/api/models/openrouter.md

@@ -0,0 +1,7 @@
+# `pydantic_ai.models.openrouter`
+
+## Setup
+
+For details on how to set up authentication with this model, see [model configuration for OpenRouter](../models/openrouter.md).
+
+::: pydantic_ai.models.openrouter

docs/models/openai.md

@@ -352,9 +352,10 @@ agent = Agent(model)
 
 ### OpenRouter
 
-To use [OpenRouter](https://openrouter.ai), first create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).
+[OpenRouter](https://openrouter.ai) now has dedicated support in PydanticAI with the [`OpenRouterModel`][pydantic_ai.models.openrouter.OpenRouterModel].
+For detailed documentation and examples, see the [OpenRouter documentation](openrouter.md).
 
-Once you have the API key, you can use it with the [`OpenRouterProvider`][pydantic_ai.providers.openrouter.OpenRouterProvider]:
+You can also still use OpenRouter through the OpenAI-compatible interface:
 
 ```python
 from pydantic_ai import Agent

docs/models/openrouter.md

@@ -0,0 +1,94 @@
+# OpenRouter
+
+## Install
+
+To use `OpenRouterModel`, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `openrouter` optional group:
+
+```bash
+pip/uv-add "pydantic-ai-slim[openrouter]"
+```
+
+## Configuration
+
+To use [OpenRouter](https://openrouter.ai/) through their API, go to [openrouter.ai/keys](https://openrouter.ai/keys) and follow your nose until you find the place to generate an API key.
+
+`OpenRouterModelName` contains a list of available OpenRouter models.
+
+## Environment variable
+
+Once you have the API key, you can set it as an environment variable:
+
+```bash
+export OPENROUTER_API_KEY='your-api-key'
+```
+
+You can then use `OpenRouterModel` with the default provider:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+
+model = OpenRouterModel('google/gemini-2.5-flash-lite')
+agent = Agent(model)
+...
+```
+
+Or initialise the model with an explicit provider:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+from pydantic_ai.providers.openrouter import OpenRouterProvider
+
+provider = OpenRouterProvider(api_key='your-api-key')
+model = OpenRouterModel('google/gemini-2.5-flash-lite', provider=provider)
+agent = Agent(model)
+...
+```
+
+## Custom HTTP Client
+
+You can customize the HTTP client by using the `OpenRouterProvider`:
+
+```python
+from httpx import AsyncClient
+
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+from pydantic_ai.providers.openrouter import OpenRouterProvider
+
+custom_http_client = AsyncClient(timeout=30)
+provider = OpenRouterProvider(
+    api_key='your-api-key',
+    http_client=custom_http_client,
+)
+model = OpenRouterModel('google/gemini-2.5-flash-lite', provider=provider)
+agent = Agent(model)
+...
+```
+
+## Structured Output
+
+You can use OpenRouter models with structured output by providing a Pydantic model as the `output_type`:
+
+```python {noqa="I001"}
+from pydantic import BaseModel
+
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+
+class OlympicsLocation(BaseModel):
+    city: str
+    country: str
+
+model = OpenRouterModel('google/gemini-2.5-flash-lite')
+agent = Agent(model, output_type=OlympicsLocation)
+
+result = agent.run_sync('Where were the olympics held in 2012?')
+print(f'City: {result.output.city}')
+#> City: London
+print(f'Country: {result.output.country}')
+#> Country: United Kingdom
+```
+
+The model will validate and parse the response into your specified Pydantic model, allowing type-safe access to structured data fields via `result.output.field_name`.

docs/models/overview.md

@@ -10,6 +10,7 @@ Pydantic AI is model-agnostic and has built-in support for multiple model provid
 * [Cohere](cohere.md)
 * [Bedrock](bedrock.md)
 * [Hugging Face](huggingface.md)
+* [OpenRouter](openrouter.md)
 
 ## OpenAI-compatible Providers
 
@@ -18,7 +19,6 @@ In addition, many providers are compatible with the OpenAI API, and can be used
 - [DeepSeek](openai.md#deepseek)
 - [Grok (xAI)](openai.md#grok-xai)
 - [Ollama](openai.md#ollama)
-- [OpenRouter](openai.md#openrouter)
 - [Vercel AI Gateway](openai.md#vercel-ai-gateway)
 - [Perplexity](openai.md#perplexity)
 - [Fireworks AI](openai.md#fireworks-ai)

mkdocs.yml

@@ -34,6 +34,7 @@ nav:
           - models/groq.md
           - models/mistral.md
           - models/huggingface.md
+          - models/openrouter.md
       - Tools & Toolsets:
           - tools.md
           - tools-advanced.md
@@ -123,6 +124,7 @@ nav:
           - api/models/huggingface.md
           - api/models/instrumented.md
           - api/models/mistral.md
+          - api/models/openrouter.md
           - api/models/test.md
           - api/models/function.md
           - api/models/fallback.md