Official Python SDK for the OpenRouter API — a unified gateway to 300+ LLM models across providers (OpenAI, Anthropic, Google, Meta, Mistral, etc.) via a single OpenAI-compatible endpoint. Auto-generated from OpenRouter's OpenAPI spec and updated on every API change. Fully typed with Pydantic. SDK is explicitly in beta — breaking changes can occur between minor versions without a major version bump. IMPORTANT: There are multiple competing 'openrouter' packages on PyPI (openrouter, openrouter-client, python-open-router). Only 'openrouter' (by OpenRouter) is the official SDK.
pip install openrouterVerified import paths — ran on the pinned version, not inferred.
Always use OpenRouter as a context manager to ensure HTTPX connections are released. The OpenAI SDK approach (with base_url override) is simpler and more widely used in practice — consider it as a primary option if you already have openai installed.
Pin to an exact version: pip install openrouter==0.7.11. Do not use unpinned installs in production.
Only install 'openrouter' (the official SDK by OpenRouter). Verify with: pip show openrouter — author should be 'OpenRouter', license 'Apache-2.0'.
Always use: 'with OpenRouter(api_key=...) as client:' (sync) or 'async with OpenRouter(api_key=...) as client:' (async).
Always use 'provider/model-name' format. Browse available models at openrouter.ai/models.
For simple use cases, consider: from openai import OpenAI; client = OpenAI(api_key=OPENROUTER_API_KEY, base_url='https://openrouter.ai/api/v1'). No extra package needed.
Ensure the `OPENROUTER_API_KEY` environment variable is correctly set in your execution environment before running the application. For example: `export OPENROUTER_API_KEY='YOUR_KEY_HERE'` or pass it via your deployment system.
Ensure you have installed the *official* `openrouter` package by OpenRouter: `pip install openrouter`
Set your OpenRouter API key as an environment variable named `OPENROUTER_API_KEY`. If using `python-dotenv`, ensure it's loaded. For direct client initialization, pass `api_key` explicitly.
```python
import os
from openrouter import OpenRouter
# Ensure OPENROUTER_API_KEY is set in your environment or .env file
client = OpenRouter(api_key=os.getenv("OPENROUTER_API_KEY"))
# Or, if integrating with libraries like LiteLLM, ensure your .env has:
# OPENROUTER_API_KEY="your_api_key_here"
# OPENAI_API_BASE="https://openrouter.ai/api/v1"
```This issue often requires updates within the `pydantic-ai` library or handling specific OpenRouter error responses. For immediate workarounds, consider trying different models, adjusting request parameters (e.g., streaming settings), or implementing custom error parsing if directly using the OpenRouter API without strict Pydantic AI validation. Check for newer versions of `pydantic-ai` or `openrouter` that might have addressed this compatibility. A potential fix involves using `OpenRouterModel` from `pydantic_ai.models.openrouter` if available, or catching `UnexpectedModelBehavior` and inspecting the raw response if possible.
Choose an OpenRouter model that explicitly supports tool use. You can check the OpenRouter documentation or model listings to identify models compatible with function calling.
```python
from openrouter import OpenRouter
client = OpenRouter(api_key=os.getenv("OPENROUTER_API_KEY"))
response = client.chat.completions.create(
model="openrouter/your-tool-use-compatible-model", # e.g., 'openai/gpt-4o' or other models listed as supporting tools
messages=[
{"role": "user", "content": "What's the weather like in Paris?"}
],
tools=[
# Your tool definitions here
]
)
```