OpenRouter

OpenRouter provides a single API endpoint to access models from OpenAI, Anthropic, Google, Meta, Mistral, and many other providers. It handles routing, fallback, rate limits, and usage tracking through an OpenAI-compatible API.

Setup

# Set your API key
export OPENROUTER_API_KEY="sk-or-v1-your-key"

# Base URL for all API calls
# https://openrouter.ai/api/v1

Basic API Usage

Chat Completions

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {"role": "user", "content": "What is OpenRouter?"}
    ]
  }'

Python with OpenAI SDK

from openai import OpenAI

# Use OpenRouter as a drop-in replacement
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-v1-your-key",
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-20250514",
    messages=[
        {"role": "user", "content": "Explain quantum computing simply"}
    ],
    max_tokens=1024,
)
print(response.choices[0].message.content)

TypeScript / Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultHeaders: {
    "HTTP-Referer": "https://myapp.com",  // For rankings
    "X-Title": "My App",                   // For dashboard display
  },
});

const response = await client.chat.completions.create({
  model: "google/gemini-2.5-pro",
  messages: [{ role: "user", content: "Hello" }],
});

Model Selection

Available Model Families

# List all available models
curl -s https://openrouter.ai/api/v1/models | python3 -m json.tool

# Popular model identifiers:
# openai/gpt-4o
# openai/gpt-4o-mini
# anthropic/claude-sonnet-4-20250514
# anthropic/claude-haiku-4-20250514
# google/gemini-2.5-pro
# meta-llama/llama-3.1-405b-instruct
# mistralai/mistral-large
# deepseek/deepseek-chat

Auto-routing

# Let OpenRouter pick the best model automatically
response = client.chat.completions.create(
    model="openrouter/auto",  # Automatic model selection
    messages=[{"role": "user", "content": "Complex reasoning task"}],
)

Streaming

# Stream responses
stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Write a poem"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Function Calling / Tools

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["location"]
            }
        }
    }],
    tool_choice="auto",
)

# Check if the model wants to call a tool
if response.choices[0].message.tool_calls:
    for call in response.choices[0].message.tool_calls:
        print(f"Function: {call.function.name}")
        print(f"Args: {call.function.arguments}")

Fallback Routing

# Configure provider fallback preferences
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "route": "fallback",  # Enable fallback routing
        "provider": {
            "order": ["OpenAI", "Azure"],  # Try OpenAI first, then Azure
            "allow_fallbacks": True,
        }
    },
)

Provider Preferences

# Require specific providers or exclude others
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "provider": {
            "require_parameters": True,  # Only use providers supporting all params
            "data_collection": "deny",   # Exclude providers that train on data
            "order": ["OpenAI"],
        }
    },
)

Rate Limits and Usage

# Check your current rate limits and credits
curl -s https://openrouter.ai/api/v1/auth/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | python3 -m json.tool

# Response includes:
# - rate limit info
# - credits remaining
# - usage this period

Usage Tracking

# Track costs per request in response headers
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

# Access usage info from the response
print(f"Prompt tokens: {response.usage.prompt_tokens}")
print(f"Completion tokens: {response.usage.completion_tokens}")
print(f"Total tokens: {response.usage.total_tokens}")
# Cost info available in response headers and dashboard

Transforms

# Enable prompt transforms for model compatibility
response = client.chat.completions.create(
    model="meta-llama/llama-3.1-70b-instruct",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "transforms": ["middle-out"],  # Compress long prompts to fit context
    },
)

Structured Output

# Request JSON output
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[
        {"role": "user", "content": "List 3 programming languages as JSON"}
    ],
    response_format={"type": "json_object"},
)

Multi-modal (Vision)

# Send images to vision-capable models
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {
                "type": "image_url",
                "image_url": {"url": "https://example.com/image.png"}
            }
        ]
    }],
)

Cost Management

# View model pricing
curl -s https://openrouter.ai/api/v1/models | python3 -c "
import sys, json
models = json.load(sys.stdin)['data']
for m in sorted(models, key=lambda x: x['id'])[:10]:
    p = m.get('pricing', {})
    print(f\"{m['id']}: prompt=\${p.get('prompt','?')}/tok completion=\${p.get('completion','?')}/tok\")
"