openrouter-free-models 0.1.0

openrouter-free-models - Find the best working free model on OpenRouter

openrouter-free-models

Find the best working free LLM model on OpenRouter.

Automatically tests available free models and returns the first one with available quota.

Installation

pip install openrouter-free-models

Requirements

• Python 3.8+
• OpenRouter API key (get one at https://openrouter.ai/keys)

Quick Start

from openrouter_free_models import get_best_free_model

# Get the best working free model
model = get_best_free_model(api_key="your_api_key")

# Access model information
print(model.name)              # 'google/gemini-flash-1.5'
print(model.context_length)    # 1000000
print(model.provider)          # 'google'
print(model.supports_tools)    # True

# Get all info as dictionary
info = model.to_dict()

Usage

Using convenience function

from openrouter_free_models import get_best_free_model

model = get_best_free_model(api_key="your_api_key")
print(f"Using: {model.name}")

Using FreeModel class directly

from free_router import FreeModel
from openrouter_free_models import FreeModel

model = FreeModel(api_key="your_api_key")
print(model.name)
print(model.context_length)

Environment variable

Set your API key as environment variable:

export OPENROUTER_API_KEY="your_api_key_here"

import os
from openrouter_free_models import get_best_free_model

model = get_best_free_model(api_key=os.environ['OPENROUTER_API_KEY'])

API Reference

get_best_free_model(api_key: str) -> FreeModel

Convenience function that returns a FreeModel instance with the best working model.

Parameters:

• api_key (str): Your OpenRouter API key (required)

Returns: FreeModel instance

Raises: Exception if no working free model is found

FreeModel(api_key: str)

Main class for finding the best free model.

Parameters:

• api_key (str): Your OpenRouter API key (required)

Properties:

• name (str): Model identifier (e.g., 'google/gemini-flash-1.5')
• context_length (int): Maximum context length in tokens
• provider (str): Provider name (e.g., 'google', 'meta-llama')
• supports_tools (bool): Whether model supports function calling

Methods:

• to_dict() -> dict: Returns all model information as a dictionary

ModelInfo Object

Returned model information includes:

Attribute	Type	Description
name	str	Full model identifier
context_length	int	Context window size in tokens
provider	str	Provider (extracted from name)
supports_tools	bool	Function calling support

How It Works

1. Fetches all free models from OpenRouter API
2. Sorts them by context length (largest first)
3. Tests each model with a tiny request to check for available quota
4. Returns the first working model with quota
5. Raises exception if no model has available quota

Example Output

>>> from openrouter_free_models import get_best_free_model
>>> model = get_best_free_model(api_key="sk-...")
🔍 Searching for free models on OpenRouter...
📋 Found 23 free models. Testing for available quota...
   [1/10] Testing google/gemini-flash-1.5... ❌ No quota (402)
   [2/10] Testing meta-llama/llama-3-8b-instruct... ✅ WORKING

>>> print(model.name)
meta-llama/llama-3-8b-instruct

>>> print(model.context_length)
8192

>>> print(model.to_dict())
{'name': 'meta-llama/llama-3-8b-instruct', 'context_length': 8192, 'provider': 'meta-llama', 'supports_tools': True}

Error Handling

try:
    model = get_best_free_model(api_key="your_key")
except Exception as e:
    print(f"Failed: {e}")
    # All free models have exhausted their quota
    # Try again later or use a paid model

License

MIT

Links

• OpenRouter
• Get API Key
• Source Code

Contributing

Issues and pull requests are welcome.