A Practical Guide to OpenRouter: Unified LLM APIs with Free Models

import os
import json
import time
from openai import OpenAI
from typing import Iterator, Optional, Dict, Any

# Initialize OpenRouter client
# Get API key from https://openrouter.ai/keys (free to sign up)
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.getenv("OPENROUTER_API_KEY"),
    default_headers={
        "HTTP-Referer": "https://your-app.com",  # Required for free tier
        "X-Title": "Your App Name",  # Shows in OpenRouter dashboard
    }
)

# Define model routing strategy with current free models
MODELS = {
    "reasoning": "nvidia/nemotron-3-super:free",
    "coding": "openai/gpt-oss-20b:free",
    "summarization": "google/gemma-4-31b:free",
    "long_context": "nvidia/nemotron-3-nano-30b-a3b:free",
    "multimodal": "minimax/minimax-m2.5:free",
    "fallback": "openrouter/free",
}

class FreeModelAgent:
    def __init__(self):
        self.usage_stats = {"total_tokens": 0, "requests": 0}
    
    def chat(self, task: str, message: str, **kwargs) -> Dict[str, Any]:
        model = MODELS.get(task, MODELS["fallback"])
        
        try:
            response = client.chat.completions.create(
                model=model,
                messages=[{"role": "user", "content": message}],
                temperature=kwargs.get("temperature", 0.7),
                max_tokens=kwargs.get("max_tokens", 2048),
            )
            
            tokens = response.usage.total_tokens
            self.usage_stats["total_tokens"] += tokens
            self.usage_stats["requests"] += 1
            
            return {
                "content": response.choices[0].message.content,
                "model": response.model,
            }
        except Exception as e:
            print(f"Failed with {model}: {e}")
            if model != MODELS["fallback"]:
                return self.chat(task, message, **kwargs)
            raise

if __name__ == "__main__":
    agent = FreeModelAgent()
    result = agent.chat("coding", "Write a Python function for fibonacci.")
    print(result["content"])

def stream_response(
    prompt: str, 
    model: str = "openrouter/free"
) -> Optional[str]:
    """Stream a response token by token."""
    try:
        stream = client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": prompt}],
            stream=True,
        )
        
        full_response = ""
        for chunk in stream:
            content = chunk.choices[0].delta.content
            if content:
                full_response += content
                print(content, end="", flush=True)
        
        print()
        return full_response
    except Exception as e:
        print(f"Stream failed: {e}")
        return None

def get_weather(location: str) -> str:
    """Mock weather function."""
    return f"The weather in {location} is sunny, 22°C."

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                },
                "required": ["location"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="openai/gpt-oss-20b:free",
    messages=[{"role": "user", "content": "What is the weather in London?"}],
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message
if message.tool_calls:
    for tool_call in message.tool_calls:
        if tool_call.function.name == "get_weather":
            import json
            args = json.loads(tool_call.function.arguments)
            weather = get_weather(args["location"])
            print(f"Weather: {weather}")

def select_free_model(task_type: str, complexity: str = "medium") -> str:
    """Select the best free model based on task and complexity."""
    free_models = {
        "simple": {"chat": "google/gemma-4-31b:free"},
        "medium": {"chat": "nvidia/nemotron-3-super:free"},
        "complex": {"reasoning": "nvidia/nemotron-3-super:free"},
    }
    return free_models.get(complexity, {}).get(task_type, "openrouter/free")

model = select_free_model("chat", "simple")
print(f"Selected model: {model}")