### Run All Basic Examples Sequentially

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Iterate through and run a list of basic example scripts, printing separators between each execution.

```bash
for file in basic_chat.py streaming_chat.py function_calling.py; do
    echo "Running $file..."
    python "$file"
    echo "---"
done
```

--------------------------------

### Multi-turn Conversation Setup

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples.md

Prepare for multi-turn conversations by defining tools and parameters. This example sets up a mock database search function using helper utilities from 'openrouter_client'.

```python
from openrouter_client import OpenRouterClient
from openrouter_client.tools import (
    build_tool_definition,
    build_parameter_schema
)
from openrouter_client.models import (
    StringParameter,
    NumberParameter,
    FunctionCall,
    ChatCompletionTool
)
import json

def search_database(query: str, category: str = "all") -> dict:
    """Mock database search function."""
    return {
        "query": query,
        "category": category,
        "results": [
            {"title": f"Result 1 for {query}", "score": 0.95},
            {"title": f"Result 2 for {query}", "score": 0.87}
        ]
    }
```

--------------------------------

### Run Text Completions Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute the text completions example script. This script demonstrates usage of the text completion endpoint.

```bash
python text_completions.py
```

--------------------------------

### Run Credits and Usage Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute the credits and usage example script. This script demonstrates checking credit balance and monitoring API usage.

```bash
python credits_and_usage.py
```

--------------------------------

### Create Message Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/types.md

Example showing how to create a message object with a specified role and content.

```python
from openrouter_client.models import Message

message = Message(
    role="user",
    content="What's the weather in NYC?"
)
```

--------------------------------

### Environment Variable Configuration Setup

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/configuration.md

Provides examples of setting OpenRouter client configuration via environment variables. This is useful for managing secrets and settings outside of the code.

```bash
# Set via environment variables
export OPENROUTER_API_KEY="sk-or-v1-மையில்"
export OPENROUTER_PROVISIONING_API_KEY="sk-prov-மையில்"
export OPENROUTER_TIMEOUT="120"
export OPENROUTER_RETRIES="5"
export OPENROUTER_LOG_LEVEL="DEBUG"
```

--------------------------------

### Run Prompt Caching Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute the prompt caching example script. This script demonstrates prompt caching for cost optimization.

```bash
python prompt_caching.py
```

--------------------------------

### Run Specific Example with Debug Output

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute a specific example script with debug output enabled by setting the OPENROUTER_LOG_LEVEL environment variable.

```bash
OPENROUTER_LOG_LEVEL=DEBUG python function_calling.py
```

--------------------------------

### Create Function Definition Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/types.md

Example demonstrating how to create a function definition using FunctionDefinition, FunctionParameters, and StringParameter.

```python
from openrouter_client.models import FunctionDefinition, FunctionParameters, StringParameter

function = FunctionDefinition(
    name="get_weather",
    description="Get weather for a location",
    parameters=FunctionParameters(
        type="object",
        properties={
            "location": StringParameter(
                type="string",
                description="City and state"
            )
        },
        required=["location"]
    )
)
```

--------------------------------

### Run Function Calling Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute the function calling example script. This script showcases function calling and tool integration with the client.

```bash
python function_calling.py
```

--------------------------------

### Run Model Management Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute the model management example script. This script covers listing, filtering, and retrieving model information.

```bash
python model_management.py
```

--------------------------------

### Install OpenRouter Python Client

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/README.md

Install the unofficial OpenRouter Python client using pip.

```bash
pip install openrouter-client-unofficial
```

--------------------------------

### Run Advanced Usage Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute the advanced usage example script. This script covers advanced patterns like context managers and concurrent requests.

```bash
python advanced_usage.py
```

--------------------------------

### Enable Additional Example Features

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Uncomment specific demonstration functions within the main execution block to run additional features of an example.

```python
if __name__ == "__main__":
    main()
    # Uncomment to run additional examples
    # demonstrate_advanced_feature()
    # demonstrate_error_cases()
```

--------------------------------

### Run Streaming Chat Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute the streaming chat example script. This script demonstrates real-time streaming responses for chat completions.

```bash
python streaming_chat.py
```

--------------------------------

### Run Basic Chat Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute the basic chat example script. This script covers simple chat completions, system messages, and multi-turn conversations.

```bash
python basic_chat.py
```

--------------------------------

### Example: Getting Specific Model Context Length

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/client.md

Initializes the client and retrieves the context length for the 'anthropic/claude-3-opus' model, then prints the result.

```python
client = OpenRouterClient(api_key="sk-...")
max_tokens = client.get_context_length("anthropic/claude-3-opus")
print(f"Claude 3 Opus supports {max_tokens} tokens")  # 200000 tokens
```

--------------------------------

### Using OpenRouter Client as a Context Manager

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples.md

Demonstrates the basic setup for using the OpenRouter client, including initialization with an API key.

```python
from openrouter_client import OpenRouterClient


```

--------------------------------

### Run Error Handling Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples/README.md

Execute the error handling example script. This script demonstrates comprehensive error handling patterns for API calls.

```bash
python error_handling.py
```

--------------------------------

### Quickstart: Initialize and Chat Completion

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/README.md

Initialize the OpenRouter client and perform a basic chat completion. Ensure your API key is set as an environment variable or passed directly.

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

--------------------------------

### Initialization

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Demonstrates various ways to initialize the OpenRouterClient, including basic setup, with provisioning keys, custom configurations, and using it as a context manager.

```APIDOC
## Initialization

### Description
Initialize the `OpenRouterClient` with your API key. Optional parameters include `provisioning_api_key`, `timeout`, and `retries`.

### Usage
```python
from openrouter_client import OpenRouterClient

# Basic initialization
client = OpenRouterClient(api_key="sk-...")

# With provisioning key
client = OpenRouterClient(
    api_key="sk-...",
    provisioning_api_key="sk-prov-..."
)

# Custom configuration
client = OpenRouterClient(
    api_key="sk-...",
    timeout=120,
    retries=5,
    backoff_factor=0.3
)

# Using as a context manager
with OpenRouterClient(api_key="sk-...") as client:
    response = client.chat.create(...) 
```
```

--------------------------------

### OpenRouterClient Initialization Examples

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/client.md

Demonstrates various ways to initialize the OpenRouterClient, including using an API key directly, relying on environment variables, and configuring advanced parameters. Also shows usage as a context manager.

```python
from openrouter_client import OpenRouterClient

# Basic initialization with API key
client = OpenRouterClient(api_key="sk-...")

# With environment variable (set OPENROUTER_API_KEY)
client = OpenRouterClient()

# With custom configuration
client = OpenRouterClient(
    api_key="sk-...",
    provisioning_api_key="sk-...",
    timeout=120,
    retries=5,
    backoff_factor=0.3
)

# Use as context manager
with OpenRouterClient(api_key="sk-...") as client:
    response = client.chat.create(
        model="anthropic/claude-3-opus",
        messages=[{"role": "user", "content": "Hello!"}]
    )
```

--------------------------------

### Save Stream State for Resumption Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/errors.md

Shows how to initiate a streaming request with a `state_file` parameter, allowing for potential resumption if interrupted. This example catches `KeyboardInterrupt` to simulate an interruption and indicate state saving.

```python
from openrouter_client import OpenRouterClient
from openrouter_client.exceptions import ResumeError

client = OpenRouterClient(api_key="sk-...")

try:
    # Save state for resumption
    for chunk in client.chat.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Very long task..."}],
        stream=True,
        state_file="stream_state.json"
    ):
        print(chunk.choices[0].delta.content, end="")
except KeyboardInterrupt:
    print("\nStream interrupted, state saved")
```

--------------------------------

### Install OpenRouter Python Client with Development Dependencies

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/index.md

Install the OpenRouter Python client package with development dependencies. This is useful for contributing to the project or running tests.

```bash
pip install openrouter-client-unofficial[dev]
```

--------------------------------

### Install PyNaCl for Secure Key Storage

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/README.md

Install the PyNaCl library to enable enhanced security for API key storage. When available, keys are encrypted in memory and securely wiped after use.

```bash
pip install pynacl
```

--------------------------------

### Install PyNaCl for Encrypted Key Storage

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/configuration.md

Install the PyNaCl library to enable automatic in-memory encryption of API keys. The keys are decrypted only when needed for requests.

```bash
# Install PyNaCl for encryption
pip install pynacl
```

--------------------------------

### Example: Refreshing Context Lengths

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/client.md

Initializes the client and then calls `refresh_context_lengths` to retrieve model context lengths, printing the length for a specific model.

```python
client = OpenRouterClient(api_key="sk-...")
context_lengths = client.refresh_context_lengths()
print(context_lengths["anthropic/claude-3-opus"])  # 200000
```

--------------------------------

### Access Response Data Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/types.md

Demonstrates how to access various fields from a client response, including message content, usage tokens, and checking for tool calls.

```python
response = client.chat.create(
    model="anthropic/claude-3-opus",
    messages=[...]
)

# Access response fields
print(response.choices[0].message.content)
print(response.usage.prompt_tokens)
print(response.usage.completion_tokens)

# Check for tool calls
if response.choices[0].message.tool_calls:
    for tool_call in response.choices[0].message.tool_calls:
        print(f"Tool: {tool_call.function.name}")
        print(f"Args: {tool_call.function.arguments}")
```

--------------------------------

### Docstring Parsing Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/tools.md

Illustrates the Google-style docstring format used for extracting parameter descriptions for tools. This format helps the system understand the arguments and return values of your tools.

```python
@tool
def function(arg1: str, arg2: int) -> str:
    """Brief function description.
    
    Args:
        arg1: Description of arg1
        arg2: Description of arg2
        
    Returns:
        Description of return value
    """
```

--------------------------------

### Manual Rate Limit and Credit Management

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/advanced-features.md

Check current rate limits and credit balance. Includes an example of waiting for rate limit reset if necessary.

```python
# Check current rate limits
rate_limits = client.calculate_rate_limits()
print(f"Requests per minute: {rate_limits['requests_per_minute']}")
print(f"Tokens per minute: {rate_limits['tokens_per_minute']}")

# Check credit balance
credits = client.credits.get()
print(f"Current balance: ${credits.data.credits}")

# Wait for rate limit reset if needed
import time
if rate_limits['requests_per_minute'] < 10:
    print("Low rate limit, waiting...")
    time.sleep(60)  # Wait for reset
```

--------------------------------

### Async-Style Usage with Streaming Responses

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples.md

This example shows how to handle streaming responses from the API. It processes chunks of the response as they arrive, allowing for real-time display and intermediate processing like word counting.

```python
from openrouter_client import OpenRouterClient
import sys

client = OpenRouterClient(api_key="your-api-key")

def stream_with_processing():
    """Stream response and process chunks as they arrive."""
    stream = client.chat.create(
        model="anthropic/claude-3-opus",
        messages=[{"role": "user", "content": "Write a detailed explanation of quantum computing"}],
        stream=True,
        max_tokens=1000
    )
    
    full_response = ""
    chunk_count = 0
    
    print("Assistant: ", end="")
    for chunk in stream:
        chunk_count += 1
        delta = chunk.choices[0].delta
        
        if delta.content:
            content = delta.content
            full_response += content
            print(content, end="", flush=True)
            
            # Process chunks in real-time (e.g., word counting)
            if chunk_count % 10 == 0:
                word_count = len(full_response.split())
                sys.stderr.write(f"\r[Words: {word_count}]")
                sys.stderr.flush()
    
    print()  # New line
    print(f"\nStream completed. Total words: {len(full_response.split())}")
    return full_response

# Run streaming example
result = stream_with_processing()
```

--------------------------------

### Function Calling with @tool Decorator

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples.md

Utilize the @tool decorator for simplified function calling integration. This example defines a 'get_weather' function and uses it within a chat completion. Ensure 'openrouter_client' and 'requests' are installed.

```python
from openrouter_client import OpenRouterClient, tool
import requests

@tool
def get_weather(location: str, unit: str = "celsius") -> dict:
    """Get current weather for a location.
    
    Args:
        location: The city and state/country
        unit: Temperature unit (celsius or fahrenheit)
    """
    # Mock implementation - replace with real weather API
    return {
        "location": location,
        "temperature": 22,
        "unit": unit,
        "condition": "Sunny",
        "humidity": 65
    }

client = OpenRouterClient(api_key="your-api-key")

response = client.chat.create(
    model="anthropic/claude-3-opus",
    messages=[{"role": "user", "content": "What's the weather like in Paris?"}],
    tools=[get_weather.to_dict()],
    tool_choice="auto"
)

# Process tool calls
if response.choices[0].message.tool_calls:
    for tool_call in response.choices[0].message.tool_calls:
        if tool_call.function.name == "get_weather":
            result = get_weather.execute(tool_call.function.arguments)
            print(f"Weather result: {result}")
else:
    print(response.choices[0].message.content)
```

--------------------------------

### Handle ProviderError Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/errors.md

Demonstrates how to catch and handle `ProviderError` when interacting with the OpenRouter client. It shows logging the error details and attempting a fallback to a different model provider.

```python
from openrouter_client import OpenRouterClient
from openrouter_client.exceptions import ProviderError

client = OpenRouterClient(api_key="sk-...")

try:
    response = client.chat.create(
        model="anthropic/claude-3-opus",
        messages=[{"role": "user", "content": "Hello"}]
    )
except ProviderError as e:
    print(f"Provider {e.provider} error: {e.message}")
    print(f"Status: {e.status_code}")
    
    # Fallback to different provider
    if e.provider == "anthropic":
        print("Anthropic error, trying OpenAI...")
        response = client.chat.create(
            model="openai/gpt-4",
            messages=[{"role": "user", "content": "Hello"}]
        )
```

--------------------------------

### Chat Completion with Tool Usage

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples.md

Demonstrates how to use the chat completion endpoint with custom tools. This involves defining a tool, sending it with a user message, executing the tool based on the assistant's response, and then getting a final response incorporating the tool's results.

```python
from openrouter_client import OpenRouterClient
import json

# Assume search_database and build_tool_definition are defined elsewhere
# For demonstration, let's define dummy versions:
def search_database_func(query: str, category: str = "all") -> dict:
    """Search for information in the database."""
    print(f"Searching database for query: {query}, category: {category}")
    # Dummy results
    return {"results": [f"Result for {query} in {category}"]}

def build_tool_definition(func):
    # Dummy tool definition builder
    return {"type": "function", "function": {"name": func.__name__, "description": func.__doc__, "parameters": { "type": "object", "properties": { "query": {"type": "string"}, "category": {"type": "string"} } }, "required": ["query"] }}

search_tool = build_tool_definition(search_database_func)

client = OpenRouterClient(api_key="your-api-key")

def conversation():
    messages = [
        {"role": "system", "content": "You are a helpful search assistant."}
    ]
    
    # First user message
    user_input = "Find information about machine learning"
    print(f"User: {user_input}")
    messages.append({"role": "user", "content": user_input})
    
    # Get assistant response
    response = client.chat.create(
        model="anthropic/claude-3-opus",
        messages=messages,
        tools=[search_tool]
    )
    
    assistant_message = response.choices[0].message
    messages.append(assistant_message.dict())
    
    # Handle tool calls
    if assistant_message.tool_calls:
        print("Assistant is searching...")
        
        for tool_call in assistant_message.tool_calls:
            # Execute the tool (parse arguments manually)
            args = json.loads(tool_call.function.arguments)
            result = search_database_func(**args) # Use the dummy function
            
            # Add tool response to conversation
            tool_response = {
                "role": "tool",
                "content": json.dumps(result),
                "tool_call_id": tool_call.id
            }
            messages.append(tool_response)
            
            print(f"Search results: {json.dumps(result, indent=2)}")
        
        # Get final response with tool results
        final_response = client.chat.create(
            model="anthropic/claude-3-opus",
            messages=messages
        )
        print(f"Assistant: {final_response.choices[0].message.content}")
    else:
        print(f"Assistant: {assistant_message.content}")

conversation()

```

--------------------------------

### Initialize CompletionsEndpoint

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/completions.md

Demonstrates how to initialize the CompletionsEndpoint by creating an OpenRouterClient instance. This is a prerequisite for making any completion requests.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(api_key="sk-...")
# client.completions is a CompletionsEndpoint instance
response = client.completions.create(
    model="gpt-3.5-turbo-instruct",
    prompt="Once upon a time"
)
```

--------------------------------

### Basic Client Initialization

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/configuration.md

Demonstrates basic ways to initialize the OpenRouterClient. It can automatically read the API key from environment variables or accept it explicitly. The context manager pattern is also shown.

```python
from openrouter_client import OpenRouterClient

# Using environment variable
client = OpenRouterClient()

# Explicitly providing API key
client = OpenRouterClient(api_key="sk-or-v1-...")

# Context manager
with OpenRouterClient(api_key="sk-or-v1-...") as client:
    response = client.chat.create(...)
```

--------------------------------

### Initialize OpenRouterClient and Access Credits

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/credits.md

Demonstrates how to initialize the OpenRouterClient and access the CreditsEndpoint instance to retrieve credit information.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(api_key="sk-...")
# client.credits is a CreditsEndpoint instance
credits_info = client.credits.get()
```

--------------------------------

### Initialize OpenRouterClient and Access Generations Endpoint

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/generations.md

Demonstrates how to create an instance of OpenRouterClient and access the generations endpoint. This is a prerequisite for using any generation-related methods.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(api_key="sk-...")
# client.generations is a GenerationsEndpoint instance
generation_info = client.generations.get("gen-id-12345")
```

--------------------------------

### List and Get Model Information

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples.md

Retrieves information about available AI models. You can list all models or get details for a specific model, including its ID, name, context length, pricing, and description.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(api_key="your-api-key")

# List all models
models = client.models.list()
print("Available models:")
for model in models.data[:5]:  # Show first 5 models
    print(f"- {model.id}: {model.name}")

# Get specific model info
model_info = client.models.get("anthropic/claude-3-opus")
print(f"\nClaude 3 Opus details:")
print(f"Context length: {model_info.context_length}")
print(f"Pricing: {model_info.pricing}")
print(f"Description: {model_info.description}")
```

--------------------------------

### Create Client and Use Tools

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/tools.md

Instantiates the OpenRouter client and initiates a chat completion request, providing a list of available tools. The response may include tool calls.

```python
# Create client and use tools
client = OpenRouterClient(api_key="sk-...")

response = client.chat.create(
    model="anthropic/claude-3-opus",
    messages=[
        {
            "role": "user",
            "content": "What's the weather in NYC? Also search for NYC attractions."
        }
    ],
    tools=[get_weather, search_web, calculate]
)
```

--------------------------------

### Get Model Pricing

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Fetches the pricing information for a specific model.

```python
# Get pricing
pricing = client.models.get_model_pricing("anthropic/claude-3-opus")
```

--------------------------------

### Initialize ChatEndpoint

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/chat.md

Shows how to initialize the OpenRouterClient and access the ChatEndpoint instance.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(api_key="sk-...")
# client.chat is a ChatEndpoint instance
response = client.chat.create(
    model="anthropic/claude-3-opus",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

--------------------------------

### client.models.get_model_pricing()

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Gets the pricing for a model. Retrieves the pricing details for a specified model.

```APIDOC
## GET client.models.get_model_pricing()

### Description
Gets the pricing for a model. Retrieves the pricing details for a specified model.

### Method
GET

### Endpoint
client.models.get_model_pricing()

### Parameters
#### Path Parameters
None

#### Query Parameters
- **model_id** (string) - Required - The ID of the model to get pricing for.
```

--------------------------------

### Usage of ModelRole Enum

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/types.md

Example of using the ModelRole enum to construct chat messages.

```python
from openrouter_client.types import ModelRole

messages = [
    {"role": ModelRole.SYSTEM, "content": "You are helpful"},
    {"role": ModelRole.USER, "content": "Hello!"}
]
```

--------------------------------

### Basic Client Configuration

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/configuration.md

Instantiate the client with essential parameters like API key, base URL, and optional headers. Configure request timeout and retry attempts.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(
    api_key="your-api-key",                    # Required
    base_url="https://openrouter.ai/api/v1",   # Default base URL
    http_referer="https://your-site.com",      # Optional referer header
    x_title="Your App Name",                   # Optional app name header
    timeout=30.0,                              # Request timeout in seconds
    max_retries=3                              # Maximum retry attempts
)
```

--------------------------------

### client.credits.get()

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Gets the current credit balance. Retrieves the remaining credit balance for the account.

```APIDOC
## GET client.credits.get()

### Description
Gets the current credit balance. Retrieves the remaining credit balance for the account.

### Method
GET

### Endpoint
client.credits.get()

### Parameters
#### Path Parameters
None

#### Query Parameters
None
```

--------------------------------

### Get Model Context Length

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Directly retrieves the context length for a specified model.

```python
# Get context length
length = client.get_context_length("anthropic/claude-3-opus")
```

--------------------------------

### get

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/models.md

Retrieves detailed information about a specific model, including its context length and pricing.

```APIDOC
## get

Get information about a specific model.

```python
def get(self, model_id: str) -> ModelData
```

### Parameters

#### Path Parameters
- **model_id** (str) - Required - The model identifier (e.g., "anthropic/claude-3-opus").

### Returns
- `ModelData` - Model information including context length, pricing, description, etc.

### Raises
- `APIError` - If the API request fails.

### Example

```python
client = OpenRouterClient(api_key="sk-...")

model = client.models.get("anthropic/claude-3-opus")
print(f"ID: {model.id}")
print(f"Name: {model.name}")
print(f"Context Length: {model.context_length}")
print(f"Max Completion Tokens: {model.max_completion_tokens}")
print(f"Prompt Pricing: ${model.pricing.prompt}")
print(f"Completion Pricing: ${model.pricing.completion}")
```
```

--------------------------------

### Calculate Rate Limits and Monitor Usage

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/examples.md

Demonstrates how to calculate request and token limits based on credits and monitor the cost of a request.

```python
rate_limits = client.calculate_rate_limits()
print(f"Requests per minute: {rate_limits['requests_per_minute']}")
print(f"Tokens per minute: {rate_limits['tokens_per_minute']}")

response = client.chat.create(
    model="anthropic/claude-3-opus",
    messages=[{"role": "user", "content": "Hello!"}]
)

updated_credits = client.credits.get()
cost = credits.data.credits - updated_credits.data.credits
print(f"Request cost: ${cost:.6f}")
```

--------------------------------

### client.keys.get()

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Gets a specific API key. Retrieves information about a single API key by its hash.

```APIDOC
## GET client.keys.get()

### Description
Gets a specific API key. Retrieves information about a single API key by its hash.

### Method
GET

### Endpoint
client.keys.get()

### Parameters
#### Path Parameters
None

#### Query Parameters
- **key_hash** (string) - Required - The hash of the API key to retrieve.
```

--------------------------------

### API Key Management Operations

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/README.md

Demonstrates how to manage API keys, including creating new keys with credit limits, listing existing keys, updating them, and deleting them. Requires a provisioning API key for initialization.

```python
# Requires provisioning API key
client = OpenRouterClient(
    api_key="sk-...",
    provisioning_api_key="sk-prov-..."
)

# Create new key
new_key = client.keys.create(
    name="My App",
    limit=100.0  # $100 credit limit
)

# List keys
keys = client.keys.list()

# Update key
client.keys.update(key_hash, name="Updated Name", disabled=False)

# Delete key
client.keys.delete(key_hash)
```

--------------------------------

### client.keys.get_current()

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Gets the current API key. Retrieves information about the currently active API key.

```APIDOC
## GET client.keys.get_current()

### Description
Gets the current API key. Retrieves information about the currently active API key.

### Method
GET

### Endpoint
client.keys.get_current()

### Parameters
#### Path Parameters
None

#### Query Parameters
None
```

--------------------------------

### Initialize Client with Provisioning API Key

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/README.md

Initialize the OpenRouterClient with both your API key and a provisioning API key to manage API keys programmatically.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(
    api_key="your-api-key",
    provisioning_api_key="your-provisioning-key"
)
```

--------------------------------

### client.models.get_context_length()

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Gets the context length of a model. Retrieves the maximum context length for a specified model.

```APIDOC
## GET client.models.get_context_length()

### Description
Gets the context length of a model. Retrieves the maximum context length for a specified model.

### Method
GET

### Endpoint
client.models.get_context_length()

### Parameters
#### Path Parameters
None

#### Query Parameters
- **model_id** (string) - Required - The ID of the model to get the context length for.
```

--------------------------------

### Get Specific API Key

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves details for a specific API key using its hash.

```python
# Get specific key
key = client.keys.get("key_hash_...")
```

--------------------------------

### Get Specific Model Details

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves detailed information for a specific model, including its context length and pricing.

```python
# Get specific model
model = client.models.get("anthropic/claude-3-opus")
print(f"Context: {model.context_length}")
print(f"Pricing: {model.pricing.prompt}")
```

--------------------------------

### Initialize Client with Environment Variable

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/getting-started.md

Initialize the client without passing the API key explicitly. It will automatically use the OPENROUTER_API_KEY environment variable if set.

```python
client = OpenRouterClient()  # Will automatically use OPENROUTER_API_KEY
```

--------------------------------

### Get Model Endpoint Information

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/api-reference.md

Retrieve information about model endpoints. The result is a dictionary containing endpoint data.

```python
endpoints = client.models.list_endpoints()
print(endpoints.data)  # Dictionary of model endpoint information
```

--------------------------------

### Get Token Usage Information

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieve and print token counts (prompt, completion, total) for a chat completion response.

```python
# Get token counts
response = client.chat.create(
    model="anthropic/claude-3-opus",
    messages=[...],
    include={"usage": True}
)

usage = response.usage
print(f"Prompt tokens: {usage.prompt_tokens}")
print(f"Completion tokens: {usage.completion_tokens}")
print(f"Total: {usage.total_tokens}")
```

--------------------------------

### Create OpenRouterClient from JSON Configuration

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/configuration.md

This Python function demonstrates how to load configuration from a JSON file and use it to instantiate the OpenRouterClient. Ensure the JSON file contains an 'openrouter' key with the necessary parameters.

```python
import json
from openrouter_client import OpenRouterClient

def create_client_from_json(config_file: str):
    """Create client from JSON configuration."""
    with open(config_file, 'r') as f:
        config = json.load(f)['openrouter']
    
    return OpenRouterClient(
        api_key=config['api_key'],
        base_url=config.get('base_url'),
        timeout=config.get('timeout'),
        max_retries=config.get('max_retries'),
        http_referer=config.get('headers', {}).get('http_referer'),
        x_title=config.get('headers', {}).get('x_title')
    )

client = create_client_from_json("openrouter_config.json")
```

--------------------------------

### Handle StreamingError Example

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/errors.md

Illustrates catching `StreamingError` during a streaming chat request. It prints the error and then retries the request without streaming.

```python
from openrouter_client import OpenRouterClient
from openrouter_client.exceptions import StreamingError

client = OpenRouterClient(api_key="sk-...")

try:
    for chunk in client.chat.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Long response..."}],
        stream=True
    ):
        print(chunk.choices[0].delta.content, end="")
except StreamingError as e:
    print(f"\nStream error: {e.message}")
    # Fall back to non-streaming
    print("Retrying without streaming...")
    response = client.chat.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Long response..."}],
        stream=False
    )
    print(response.choices[0].message.content)
```

--------------------------------

### Advanced Client Configuration

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/configuration.md

Illustrates initializing the OpenRouterClient with a comprehensive set of advanced parameters, including provisioning API key, custom base URL, organization and reference IDs, and adjusted HTTP/logging settings.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(
    api_key="sk-or-v1-மையில்",
    provisioning_api_key="sk-prov-மையில்",  # For key management
    base_url="https://openrouter.ai/api/v1",  # Standard
    organization_id="org-123",  # For billing
    reference_id="ref-456",  # For tracking
    timeout=120,  # 2 minute timeout
    retries=5,  # More aggressive retries
    backoff_factor=0.3,  # Shorter backoff
    log_level="DEBUG"  # Verbose logging
)
```

--------------------------------

### Get Cache Metrics (Anthropic)

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Display cache metrics (write and read tokens) if available in the usage information for Anthropic models.

```python
# Cache metrics (Anthropic)
if hasattr(usage, 'cache_creation_input_tokens'):
    print(f"Cache write: {usage.cache_creation_input_tokens}")
    print(f"Cache read: {usage.cache_read_input_tokens}")
```

--------------------------------

### Initialize OpenRouterClient and Access Models Endpoint

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/models.md

Demonstrates how to initialize the OpenRouterClient and access the ModelsEndpoint instance to list models.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(api_key="sk-...")
# client.models is a ModelsEndpoint instance
models = client.models.list()
```

--------------------------------

### Get Credit Balance

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves the current credit balance, including remaining credits, used credits, and time until the next refresh.

```python
# Get credit balance
credits = client.credits.get()
print(f"Remaining: ${credits.get('remaining')}")
print(f"Used: ${credits.get('used')}")
print(f"Refresh in: {credits.get('refresh_rate', {}).get('seconds')}s")
```

--------------------------------

### create

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/keys.md

Creates a new API key. The API key is only shown once and must be saved securely immediately after creation. Requires provisioning API key.

```APIDOC
## create

### Description
Create a new API key (requires provisioning API key).

**Important:** The API key will only be shown once. You must save it securely immediately after creation.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
POST (implied by Python method signature)

### Endpoint
/keys (implied by Python method signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (str) - Required - Name for the API key.
- **label** (Optional[str]) - Optional - Optional label for the key.
- **limit** (Optional[float]) - Optional - Optional credit limit for the key.

### Request Example
```python
import json
from openrouter_client import OpenRouterClient

client = OpenRouterClient(
    api_key="sk-...",
    provisioning_api_key="sk-prov-..."
)

new_key = client.keys.create(
    name="Production API Key",
    label="Production",
    limit=1000.0  # $1000 credit limit
)

# IMPORTANT: Save the key securely
print("Save this key securely (it will not be shown again):")
print(new_key['key'])

# Store safely
with open('new_key.json', 'w') as f:
    json.dump({
        'key': new_key['key'],
        'hash': new_key['key_hash'],
        'name': new_key['name']
    }, f)
```

### Response
#### Success Response (200)
- **key** (str) - The actual API key (shown only once!)
- **key_hash** (str) - Hash of the key for identification
- **name** (str) - Name of the key
- **created_at** (str) - Creation timestamp
- **limit** (float) - Credit limit if set

#### Response Example
```json
{
  "key": "sk-...",
  "key_hash": "k1234...",
  "name": "Production API Key",
  "created_at": "2023-10-27T10:00:00Z",
  "limit": 1000.0
}
```

### Error Handling
- `APIError` - If the API request fails.
```

--------------------------------

### Get Specific Generation Details

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/api-reference.md

Retrieve details for a specific generation using its unique identifier. Includes status and creation timestamp.

```python
generation = client.generations.get("gen_123456789")
print(f"Status: {generation.status}")
print(f"Created: {generation.created_at}")
```

--------------------------------

### Get Specific Model Context Length

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/client.md

Retrieves the context length for a given model ID. If the model is not found, it defaults to 4096.

```python
def get_context_length(self, model_id: str) -> int
```

--------------------------------

### Configure Client for Development vs. Production

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/configuration.md

Set up the OpenRouter client with different configurations based on the environment variable 'ENVIRONMENT'. Production uses specific API keys and longer timeouts/retries, while development allows for test keys and shorter timeouts/retries with debug logging.

```python
import os

ENV = os.environ.get("ENVIRONMENT", "development")

if ENV == "production":
    client = OpenRouterClient(
        api_key=os.environ["OPENROUTER_API_KEY"],
        provisioning_api_key=os.environ.get("OPENROUTER_PROVISIONING_API_KEY"),
        timeout=120,
        retries=5,
        backoff_factor=0.3,
        log_level="WARNING"
    )
else:  # development
    client = OpenRouterClient(
        api_key=os.environ.get("OPENROUTER_API_KEY", "sk-test-..."),
        timeout=60,
        retries=3,
        backoff_factor=0.5,
        log_level="DEBUG"
    )
```

--------------------------------

### Basic Authentication with API Key

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/getting-started.md

Initialize the OpenRouter client by passing your API key directly. Ensure you replace 'your-api-key-here' with your actual key.

```python
from openrouter_client import OpenRouterClient

client = OpenRouterClient(api_key="your-api-key-here")
```

--------------------------------

### Get Model Context Length

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/models.md

Retrieves the maximum context length (in tokens) for a specific model. This is crucial for understanding input limitations.

```python
client = OpenRouterClient(api_key="sk-...")

context_length = client.models.get_context_length("anthropic/claude-3-opus")
print(f"Maximum context length: {context_length}")  # 200000
```

--------------------------------

### Initialize Client with API Key

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/README.md

Instantiate the OpenRouterClient using your API key. The client automatically fetches rate limits associated with this key upon initialization.

```python
client = OpenRouterClient(api_key="sk-...")
# Rate limits automatically configured from API key
```

--------------------------------

### Environment Variables for Configuration

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/configuration.md

Configure the client using environment variables for API key, base URL, headers, and request settings. This avoids hardcoding sensitive information.

```bash
# API key (alternative to passing in code)
export OPENROUTER_API_KEY="your-api-key"

# Base URL override
export OPENROUTER_BASE_URL="https://custom-endpoint.com/api/v1"

# Default headers
export OPENROUTER_HTTP_REFERER="https://your-site.com"
export OPENROUTER_X_TITLE="Your App Name"

# Timeout and retry settings
export OPENROUTER_TIMEOUT="60.0"
export OPENROUTER_MAX_RETRIES="5"

# Logging level
export OPENROUTER_LOG_LEVEL="INFO"
```

--------------------------------

### Get API Key Information

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/api-reference.md

Retrieves information about your API keys, such as their label and usage statistics. This is useful for monitoring and managing your API access.

```python
keys_info = client.keys.get()
print(f"Label: {keys_info.data.label}")
print(f"Usage: {keys_info.data.usage}")
```

--------------------------------

### Basic Logging Configuration

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/configuration.md

Set up global logging for the OpenRouter client or configure specific components with custom levels and formats.

```python
from openrouter_client import configure_logging
import logging

# Configure all OpenRouter client logging
configure_logging(level=logging.INFO)

# Or configure specific components
configure_logging(
    level=logging.DEBUG,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
```

--------------------------------

### Get Credit Balance and Usage

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/docs/api-reference.md

Fetch the current credit balance and usage information. The response provides data on credits and usage amounts.

```python
credits = client.credits.get()
print(f"Balance: ${credits.data.credits}")
print(f"Usage: ${credits.data.usage}")
```

--------------------------------

### Use Context Manager for Resource Cleanup

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/README.md

Employ the `with` statement to ensure that the OpenRouter client's resources are automatically cleaned up after use. This is the recommended way to manage client instances.

```python
with OpenRouterClient(api_key="sk-...") as client:
    response = client.chat.create(...)
# Automatic resource cleanup
```

--------------------------------

### Get Specific Model Information

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/api-reference/models.md

Retrieves detailed information for a single, specified model. This is useful for inspecting the capabilities and pricing of a particular model.

```python
client = OpenRouterClient(api_key="sk-...")

model = client.models.get("anthropic/claude-3-opus")
print(f"ID: {model.id}")
print(f"Name: {model.name}")
print(f"Context Length: {model.context_length}")
print(f"Max Completion Tokens: {model.max_completion_tokens}")
print(f"Prompt Pricing: ${model.pricing.prompt}")
print(f"Completion Pricing: ${model.pricing.completion}")
```

--------------------------------

### Environment Variable Configuration Usage

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/configuration.md

Demonstrates how the OpenRouterClient automatically utilizes environment variables for configuration when no explicit parameters are provided during initialization.

```python
# Python code - reads from environment
from openrouter_client import OpenRouterClient

client = OpenRouterClient()  # Automatically uses environment variables
```

--------------------------------

### Get Current API Key Information

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/README.md

Retrieve information about your currently active API key, including usage statistics and rate limits.

```python
# 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']}")
```

--------------------------------

### Export Optional Environment Variables

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/README.md

Configure optional settings like provisioning API key, request timeout, retries, and log level using environment variables. These allow for fine-tuning the client's behavior.

```bash
export OPENROUTER_PROVISIONING_API_KEY="sk-prov-..."
export OPENROUTER_TIMEOUT="120"
export OPENROUTER_RETRIES="5"
export OPENROUTER_LOG_LEVEL="DEBUG"
```

--------------------------------

### Models

Source: https://github.com/dingo-actual/openrouter-python-client/blob/main/_autodocs/QUICK-REFERENCE.md

Provides methods to list all available models, retrieve models with details including context length and pricing, and get specific model information.

```APIDOC
## Models

### Description
Manage and query information about available models.

### Methods
- **`client.models.list(details: bool = False)`**: Lists available models. Set `details=True` to include context length and pricing.
- **`client.models.get(model_id: str)`**: Retrieves details for a specific model.
- **`client.get_context_length(model_id: str)`**: Gets the context length for a given model.
- **`client.models.get_model_pricing(model_id: str)`**: Retrieves pricing information for a specific model.

### Request Example
```python
# List all models
models = client.models.list()

# List models with details
models = client.models.list(details=True)
for model in models.data:
    print(f"{model.id}: {model.context_length} tokens")

# Get specific model details
model = client.models.get("anthropic/claude-3-opus")
print(f"Context: {model.context_length}")
print(f"Pricing: {model.pricing.prompt}")

# Get context length
length = client.get_context_length("anthropic/claude-3-opus")

# Get pricing
pricing = client.models.get_model_pricing("anthropic/claude-3-opus")
```
```