OpenRouter Python SDK

0.7.11 · active · verified Sat Feb 28

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.

Warnings

breaking SDK is explicitly in beta. The PyPI page states: 'breaking changes between versions without a major version update'. The SDK jumped from 0.0.x to 0.1.x to 0.6.0 to 0.7.x with no major version bump. Each jump contained breaking API changes.
Fix: Pin to an exact version: pip install openrouter==0.7.11. Do not use unpinned installs in production.
gotcha Multiple competing packages on PyPI share similar names: 'openrouter' (official), 'openrouter-client' (unofficial FastAPI wrapper), 'python-open-router' (unofficial async client). pip install openrouter-client or pip install python-open-router install the wrong package with different APIs.
Fix: Only install 'openrouter' (the official SDK by OpenRouter). Verify with: pip show openrouter — author should be 'OpenRouter', license 'Apache-2.0'.
gotcha Not using OpenRouter as a context manager leaves HTTPX client connections open (file handles, sockets). In long-running services or scripts that repeatedly instantiate OpenRouter(), this causes connection pool exhaustion.
Fix: Always use: 'with OpenRouter(api_key=...) as client:' (sync) or 'async with OpenRouter(api_key=...) as client:' (async).
gotcha OpenRouter model strings include the provider prefix: 'anthropic/claude-sonnet-4-20250514', not just 'claude-sonnet-4-20250514'. Using just the model name without provider prefix may fail or route to an unexpected provider.
Fix: Always use 'provider/model-name' format. Browse available models at openrouter.ai/models.
gotcha The OpenAI SDK approach (setting base_url='https://openrouter.ai/api/v1') is often simpler and more stable than the native openrouter package, especially for teams already using the openai SDK. The OpenRouter API is OpenAI-compatible by design.
Fix: 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.

Install

pip install openrouter Official SDK (pin to specific version — SDK is in beta)
pip install openrouter==0.7.11 Pinned install (recommended per SDK docs)

Imports

OpenRouter
```
from openrouter import OpenRouter
```
Use as context manager: 'with OpenRouter(api_key=...) as client'. This ensures HTTPX connections are properly closed.

Quickstart

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.

import os
from openrouter import OpenRouter

# Sync usage — use as context manager
with OpenRouter(api_key=os.environ['OPENROUTER_API_KEY']) as client:
    # Standard completion
    response = client.chat.send(
        model='anthropic/claude-sonnet-4-20250514',
        messages=[{'role': 'user', 'content': 'Hello!'}]
    )
    print(response)

    # With provider routing preferences
    response = client.chat.send(
        model='openai/gpt-4o',
        messages=[{'role': 'user', 'content': 'Hello!'}],
        provider={
            'sort': 'price',  # or 'latency', 'throughput'
            'zdr': True       # Zero Data Retention
        }
    )

# Async usage
import asyncio
from openrouter import OpenRouter

async def main():
    async with OpenRouter(api_key=os.environ['OPENROUTER_API_KEY']) as client:
        response = await client.chat.send_async(
            model='anthropic/claude-sonnet-4-20250514',
            messages=[{'role': 'user', 'content': 'Hello!'}]
        )
        print(response)

asyncio.run(main())

# OpenAI SDK approach (no openrouter package needed)
from openai import OpenAI
client = OpenAI(
    api_key=os.environ['OPENROUTER_API_KEY'],
    base_url='https://openrouter.ai/api/v1'
)
response = client.chat.completions.create(
    model='anthropic/claude-sonnet-4-20250514',
    messages=[{'role': 'user', 'content': 'Hello!'}]
)

view raw JSON →