# OpenRouter Python Client (Unofficial)
<img src="images/openrouter_client_logo.png" alt="OpenRouter Client (Unofficial) Logo" width="830" height="415">
<br>
An unofficial Python client for [OpenRouter](https://openrouter.ai/), providing a comprehensive interface for interacting with large language models through the OpenRouter API.
## Features
- **Full API Support (Almost)**: Access all major OpenRouter endpoints including chat completions, text completions, model information, generations, credits, and API key management
- **Streaming Support**: Stream responses from chat and completion endpoints
- **Automatic Rate Limiting**: Automatically configures rate limits based on your API key's limits using SmartSurge
- **Smart Retries**: Built-in retry logic with exponential backoff for reliable API communication
- **Type Safety**: Fully typed interfaces with Pydantic models for all request and response data
- **Tool Calling**: Built-in support for tool-calling with helper functions and decorators
- **Safe Key Management**: Secure API key management with in-memory encryption and extensible secrets management
- **Comprehensive Testing**: Extensive test suite with both local unit tests and remote integration tests
## Disclaimer
This project is independently developed and is not affiliated with, endorsed, or sponsored by OpenRouter, Inc.
Your use of the OpenRouter API through this interface is subject to OpenRouter's Terms of Service, Privacy Policy, and any other relevant agreements provided by OpenRouter, Inc. You are responsible for reviewing and complying with these terms.
This project is an open-source interface designed to interact with the OpenRouter API. It is provided "as-is," without any warranty, express or implied, under the terms of the Apache 2.0 License.
## Installation
```bash
pip install openrouter-client-unofficial
```
## Quickstart
```python
from openrouter_client import OpenRouterClient
# Initialize the client
client = OpenRouterClient(
api_key="your-api-key", # Or set OPENROUTER_API_KEY environment variable
)
# Chat completion example
response = client.chat.create(
model="anthropic/claude-3-opus", # Or any other model on OpenRouter
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Tell me about OpenRouter."}
]
)
print(response.choices[0].message.content)
```
## Client Configuration
```python
from openrouter_client import OpenRouterClient
client = OpenRouterClient(
api_key="your-api-key", # API key for authentication
provisioning_api_key="your-prov-key", # Optional: for API key management
base_url="https://openrouter.ai/api/v1", # Base URL for API
organization_id="your-org-id", # Optional organization ID
reference_id="your-ref-id", # Optional reference ID
log_level="INFO", # Logging level
timeout=60.0, # Request timeout in seconds
retries=3, # Number of retries for failed requests
backoff_factor=0.5, # Exponential backoff factor
rate_limit=None, # Optional custom rate limit (auto-configured by default)
)
```
### Automatic Rate Limiting
The client automatically configures rate limits based on your API key's limits during initialization. It fetches your current key information and sets appropriate rate limits to prevent hitting API limits. This happens transparently when you create a new client instance.
If you need custom rate limiting, you can still provide your own configuration via the `rate_limit` parameter.
You can also calculate rate limits based on your remaining credits:
```python
# Calculate rate limits based on available credits
rate_limits = client.calculate_rate_limits()
print(f"Recommended: {rate_limits['requests']} requests per {rate_limits['period']} seconds")
```
## Examples
### Streaming Responses
```python
from openrouter_client import OpenRouterClient
client = OpenRouterClient(api_key="your-api-key")
# Stream the response
for chunk in client.chat.create(
model="openai/gpt-4",
messages=[
{"role": "user", "content": "Write a short poem about AI."}
],
stream=True,
):
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
```
### Function Calling
```python
from openrouter_client import OpenRouterClient, tool
from openrouter_client.models import ChatCompletionTool, FunctionDefinition, StringParameter, FunctionParameters
client = OpenRouterClient(api_key="your-api-key")
# Method 1: Using the @tool decorator (recommended)
@tool
def get_weather(location: str) -> str:
"""Get the weather for a location.
Args:
location: The city and state
Returns:
Weather information for the location
"""
# Your weather API logic here
return f"The weather in {location} is sunny."
# Method 2: Manual tool definition
weather_tool = ChatCompletionTool(
type="function",
function=FunctionDefinition(
name="get_weather",
description="Get the weather for a location",
parameters=FunctionParameters(
type="object",
properties={
"location": StringParameter(
type="string",
description="The city and state"
)
},
required=["location"]
)
)
)
# Make a request with tool
response = client.chat.create(
model="anthropic/claude-3-opus",
messages=[
{"role": "user", "content": "What's the weather like in San Francisco?"}
],
tools=[get_weather], # Using the decorated function
)
# Process tool calls
if response.choices[0].message.tool_calls:
tool_call = response.choices[0].message.tool_calls[0]
print(f"Tool called: {tool_call.function.name}")
print(f"Arguments: {tool_call.function.arguments}")
```
### Prompt Caching
```python
from openrouter_client import OpenRouterClient
client = OpenRouterClient(api_key="your-api-key")
# OpenAI models: automatic caching for prompts > 1024 tokens
response = client.chat.create(
model="openai/gpt-3.5-turbo",
messages=[
{"role": "user", "content": f"Here is a long document: {long_text}\n\nSummarize this document."}
]
)
# Anthropic models: explicit cache_control markers
response = client.chat.create(
model="anthropic/claude-3-opus",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Here is a long document:"},
# Mark this part for caching
{"type": "text", "text": long_text, "cache_control": {"type": "ephemeral"}},
{"type": "text", "text": "Summarize this document."}
]
}
]
)
```
### Context Length Management
The client provides built-in context length management:
```python
# Refresh model context lengths from the API
context_lengths = client.refresh_context_lengths()
# Get context length for a specific model
max_tokens = client.get_context_length("anthropic/claude-3-opus")
print(f"Claude 3 Opus supports up to {max_tokens} tokens")
```
### API Key Management
Manage API keys programmatically (requires provisioning API key):
```python
client = OpenRouterClient(
api_key="your-api-key",
provisioning_api_key="your-provisioning-key"
)
# Get current key information
key_info = client.keys.get_current()
print(f"Current usage: {key_info['data']['usage']} credits")
print(f"Rate limit: {key_info['data']['rate_limit']['requests']} requests per {key_info['data']['rate_limit']['interval']}")
# List all keys
keys = client.keys.list()
# Create a new key
new_key = client.keys.create(
name="My New Key",
label="Production API Key",
limit=1000.0 # Credit limit
)
```
## Available Endpoints
- `client.chat`: Chat completions API
- `client.completions`: Text completions API
- `client.models`: Model information and selection
- `client.generations`: Generation metadata and details
- `client.credits`: Credit management and usage tracking
- `client.keys`: API key management and provisioning
## License
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "openrouter-client-unofficial",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, api-client, openrouter, llm, large-language-models",
"author": null,
"author_email": "Ryan Taylor <ryan@beta-reduce.net>",
"download_url": "https://files.pythonhosted.org/packages/1d/1b/511934c4968d17bb64b043d287794dbd23ae68e0ff4c33450f5c3cea2eb5/openrouter_client_unofficial-0.0.4.tar.gz",
"platform": null,
"description": "# OpenRouter Python Client (Unofficial)\n\n<img src=\"images/openrouter_client_logo.png\" alt=\"OpenRouter Client (Unofficial) Logo\" width=\"830\" height=\"415\">\n<br>\n\nAn unofficial Python client for [OpenRouter](https://openrouter.ai/), providing a comprehensive interface for interacting with large language models through the OpenRouter API.\n\n## Features\n\n- **Full API Support (Almost)**: Access all major OpenRouter endpoints including chat completions, text completions, model information, generations, credits, and API key management\n- **Streaming Support**: Stream responses from chat and completion endpoints\n- **Automatic Rate Limiting**: Automatically configures rate limits based on your API key's limits using SmartSurge\n- **Smart Retries**: Built-in retry logic with exponential backoff for reliable API communication\n- **Type Safety**: Fully typed interfaces with Pydantic models for all request and response data\n- **Tool Calling**: Built-in support for tool-calling with helper functions and decorators\n- **Safe Key Management**: Secure API key management with in-memory encryption and extensible secrets management\n- **Comprehensive Testing**: Extensive test suite with both local unit tests and remote integration tests\n\n## Disclaimer\n\nThis project is independently developed and is not affiliated with, endorsed, or sponsored by OpenRouter, Inc.\n\nYour use of the OpenRouter API through this interface is subject to OpenRouter's Terms of Service, Privacy Policy, and any other relevant agreements provided by OpenRouter, Inc. You are responsible for reviewing and complying with these terms.\n\nThis project is an open-source interface designed to interact with the OpenRouter API. It is provided \"as-is,\" without any warranty, express or implied, under the terms of the Apache 2.0 License.\n\n## Installation\n\n```bash\npip install openrouter-client-unofficial\n```\n\n## Quickstart\n\n```python\nfrom openrouter_client import OpenRouterClient\n\n# Initialize the client\nclient = OpenRouterClient(\n api_key=\"your-api-key\", # Or set OPENROUTER_API_KEY environment variable\n)\n\n# Chat completion example\nresponse = client.chat.create(\n model=\"anthropic/claude-3-opus\", # Or any other model on OpenRouter\n messages=[\n {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"},\n {\"role\": \"user\", \"content\": \"Tell me about OpenRouter.\"}\n ]\n)\n\nprint(response.choices[0].message.content)\n```\n\n## Client Configuration\n\n```python\nfrom openrouter_client import OpenRouterClient\n\nclient = OpenRouterClient(\n api_key=\"your-api-key\", # API key for authentication\n provisioning_api_key=\"your-prov-key\", # Optional: for API key management\n base_url=\"https://openrouter.ai/api/v1\", # Base URL for API\n organization_id=\"your-org-id\", # Optional organization ID\n reference_id=\"your-ref-id\", # Optional reference ID\n log_level=\"INFO\", # Logging level\n timeout=60.0, # Request timeout in seconds\n retries=3, # Number of retries for failed requests\n backoff_factor=0.5, # Exponential backoff factor\n rate_limit=None, # Optional custom rate limit (auto-configured by default)\n)\n```\n\n### Automatic Rate Limiting\n\nThe client automatically configures rate limits based on your API key's limits during initialization. It fetches your current key information and sets appropriate rate limits to prevent hitting API limits. This happens transparently when you create a new client instance.\n\nIf you need custom rate limiting, you can still provide your own configuration via the `rate_limit` parameter.\n\nYou can also calculate rate limits based on your remaining credits:\n\n```python\n# Calculate rate limits based on available credits\nrate_limits = client.calculate_rate_limits()\nprint(f\"Recommended: {rate_limits['requests']} requests per {rate_limits['period']} seconds\")\n```\n\n## Examples\n\n### Streaming Responses\n\n```python\nfrom openrouter_client import OpenRouterClient\n\nclient = OpenRouterClient(api_key=\"your-api-key\")\n\n# Stream the response\nfor chunk in client.chat.create(\n model=\"openai/gpt-4\",\n messages=[\n {\"role\": \"user\", \"content\": \"Write a short poem about AI.\"}\n ],\n stream=True,\n):\n if chunk.choices and chunk.choices[0].delta.content:\n print(chunk.choices[0].delta.content, end=\"\")\n```\n\n### Function Calling\n\n```python\nfrom openrouter_client import OpenRouterClient, tool\nfrom openrouter_client.models import ChatCompletionTool, FunctionDefinition, StringParameter, FunctionParameters\n\nclient = OpenRouterClient(api_key=\"your-api-key\")\n\n# Method 1: Using the @tool decorator (recommended)\n@tool\ndef get_weather(location: str) -> str:\n \"\"\"Get the weather for a location.\n \n Args:\n location: The city and state\n \n Returns:\n Weather information for the location\n \"\"\"\n # Your weather API logic here\n return f\"The weather in {location} is sunny.\"\n\n# Method 2: Manual tool definition\nweather_tool = ChatCompletionTool(\n type=\"function\",\n function=FunctionDefinition(\n name=\"get_weather\",\n description=\"Get the weather for a location\",\n parameters=FunctionParameters(\n type=\"object\",\n properties={\n \"location\": StringParameter(\n type=\"string\",\n description=\"The city and state\"\n )\n },\n required=[\"location\"]\n )\n )\n)\n\n# Make a request with tool\nresponse = client.chat.create(\n model=\"anthropic/claude-3-opus\",\n messages=[\n {\"role\": \"user\", \"content\": \"What's the weather like in San Francisco?\"}\n ],\n tools=[get_weather], # Using the decorated function\n)\n\n# Process tool calls\nif response.choices[0].message.tool_calls:\n tool_call = response.choices[0].message.tool_calls[0]\n print(f\"Tool called: {tool_call.function.name}\")\n print(f\"Arguments: {tool_call.function.arguments}\")\n```\n\n### Prompt Caching\n\n```python\nfrom openrouter_client import OpenRouterClient\n\nclient = OpenRouterClient(api_key=\"your-api-key\")\n\n# OpenAI models: automatic caching for prompts > 1024 tokens\nresponse = client.chat.create(\n model=\"openai/gpt-3.5-turbo\",\n messages=[\n {\"role\": \"user\", \"content\": f\"Here is a long document: {long_text}\\n\\nSummarize this document.\"}\n ]\n)\n\n# Anthropic models: explicit cache_control markers\nresponse = client.chat.create(\n model=\"anthropic/claude-3-opus\",\n messages=[\n {\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"text\", \"text\": \"Here is a long document:\"},\n # Mark this part for caching\n {\"type\": \"text\", \"text\": long_text, \"cache_control\": {\"type\": \"ephemeral\"}},\n {\"type\": \"text\", \"text\": \"Summarize this document.\"}\n ]\n }\n ]\n)\n```\n\n### Context Length Management\n\nThe client provides built-in context length management:\n\n```python\n# Refresh model context lengths from the API\ncontext_lengths = client.refresh_context_lengths()\n\n# Get context length for a specific model\nmax_tokens = client.get_context_length(\"anthropic/claude-3-opus\")\nprint(f\"Claude 3 Opus supports up to {max_tokens} tokens\")\n```\n\n### API Key Management\n\nManage API keys programmatically (requires provisioning API key):\n\n```python\nclient = OpenRouterClient(\n api_key=\"your-api-key\",\n provisioning_api_key=\"your-provisioning-key\"\n)\n\n# Get current key information\nkey_info = client.keys.get_current()\nprint(f\"Current usage: {key_info['data']['usage']} credits\")\nprint(f\"Rate limit: {key_info['data']['rate_limit']['requests']} requests per {key_info['data']['rate_limit']['interval']}\")\n\n# List all keys\nkeys = client.keys.list()\n\n# Create a new key\nnew_key = client.keys.create(\n name=\"My New Key\",\n label=\"Production API Key\",\n limit=1000.0 # Credit limit\n)\n```\n\n## Available Endpoints\n\n- `client.chat`: Chat completions API\n- `client.completions`: Text completions API\n- `client.models`: Model information and selection\n- `client.generations`: Generation metadata and details\n- `client.credits`: Credit management and usage tracking\n- `client.keys`: API key management and provisioning\n\n## License\n\nThis project is licensed under the Apache 2.0 License - see the LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": null,
"summary": "Unofficial Python client for the OpenRouter API, providing a comprehensive interface for interacting with large language models",
"version": "0.0.4",
"project_urls": {
"Documentation": "https://github.com/dingo-actual/openrouter-python-client#readme",
"Homepage": "https://github.com/dingo-actual/openrouter-python-client",
"Issues": "https://github.com/dingo-actual/openrouter-python-client/issues",
"Repository": "https://github.com/dingo-actual/openrouter-python-client"
},
"split_keywords": [
"ai",
" api-client",
" openrouter",
" llm",
" large-language-models"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "17be2e6896442c2299b33fd930f778dd5d0677a88c53b8c2c9c5e97471dbc446",
"md5": "a5d049e4fa3f07bf874f9fa05c98f652",
"sha256": "2e5528fc2469c8ba3c0ec48eb9fd5ba4898ddd93a5637e90cb3330a0fc06e8eb"
},
"downloads": -1,
"filename": "openrouter_client_unofficial-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a5d049e4fa3f07bf874f9fa05c98f652",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 83745,
"upload_time": "2025-08-18T15:29:10",
"upload_time_iso_8601": "2025-08-18T15:29:10.754692Z",
"url": "https://files.pythonhosted.org/packages/17/be/2e6896442c2299b33fd930f778dd5d0677a88c53b8c2c9c5e97471dbc446/openrouter_client_unofficial-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1d1b511934c4968d17bb64b043d287794dbd23ae68e0ff4c33450f5c3cea2eb5",
"md5": "56726febbb234dd709aefd380c393fd2",
"sha256": "3ab0268d8ac17be55f4fdf2d557ca6400663e833e85439ebd6b40377963e6543"
},
"downloads": -1,
"filename": "openrouter_client_unofficial-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "56726febbb234dd709aefd380c393fd2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 68313,
"upload_time": "2025-08-18T15:29:11",
"upload_time_iso_8601": "2025-08-18T15:29:11.898972Z",
"url": "https://files.pythonhosted.org/packages/1d/1b/511934c4968d17bb64b043d287794dbd23ae68e0ff4c33450f5c3cea2eb5/openrouter_client_unofficial-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 15:29:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dingo-actual",
"github_project": "openrouter-python-client#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openrouter-client-unofficial"
}
JSON
