openrouter-openai-compat

OpenRouter OpenAI Compatibility

Overview

OpenRouter implements the OpenAI Chat Completions API specification (/v1/chat/completions). Existing OpenAI SDK code works with OpenRouter by changing two values: base_url and api_key. This gives you access to 400+ models from all providers through the same SDK interface.

The Two-Line Migration

Python (Before)

from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])  # OpenAI direct
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

Python (After)

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",              # Changed
    api_key=os.environ["OPENROUTER_API_KEY"],              # Changed
    default_headers={
        "HTTP-Referer": "https://your-app.com",            # Added (optional)
        "X-Title": "Your App",                             # Added (optional)
    },
)
response = client.chat.completions.create(
    model="openai/gpt-4o",  # Prefix with provider namespace
    messages=[{"role": "user", "content": "Hello"}],
)

TypeScript (After)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultHeaders: { "HTTP-Referer": "https://your-app.com", "X-Title": "Your App" },
});

const res = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});

Model ID Mapping

OpenAI Direct	OpenRouter ID
gpt-4o	openai/gpt-4o
gpt-4o-mini	openai/gpt-4o-mini
gpt-4-turbo	openai/gpt-4-turbo
o1	openai/o1
o1-mini	openai/o1-mini

You also gain access to non-OpenAI models through the same SDK:

# Same client, any provider
response = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet",  # Anthropic
    messages=[{"role": "user", "content": "Hello"}],
)

response = client.chat.completions.create(
    model="google/gemini-2.0-flash",  # Google
    messages=[{"role": "user", "content": "Hello"}],
)

What Works Identically

Feature	Status	Notes
chat.completions.create	Fully supported	Main endpoint, all parameters
stream: true	Fully supported	SSE format identical to OpenAI
tools / tool_choice	Supported	OpenRouter transforms for non-OpenAI providers
response_format: { type: "json_object" }	Supported	Basic JSON mode
response_format: { type: "json_schema" }	Supported	Strict schema mode
temperature, top_p, max_tokens	Supported	Standard parameters
stop sequences	Supported	Array of stop strings
n (multiple completions)	Supported	Multiple choices

What Differs

Feature	Difference	Workaround
Model IDs	Prefixed with provider/	Update model strings
organization param	Not used	Remove from client init
Embeddings	Limited support	Use direct provider or dedicated embedding service
Fine-tuned models	Not directly accessible	Use provider's fine-tuned model ID if hosted
logprobs	Model-dependent	Check model capabilities via /api/v1/models
Responses API	Beta support	Use /api/v1/responses endpoint

OpenRouter-Only Features

These are available through the same SDK but are unique to OpenRouter:

# Model fallbacks (try models in order)
response = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "models": [
            "anthropic/claude-3.5-sonnet",
            "openai/gpt-4o",
            "google/gemini-2.0-flash",
        ],
        "route": "fallback",
    },
)

# Provider preferences
response = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "provider": {
            "order": ["anthropic"],             # Prefer Anthropic direct
            "allow_fallbacks": True,
            "sort": "price",                    # Cheapest first
        },
    },
)

# Plugins (web search, response healing)
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "What happened today?"}],
    extra_body={
        "plugins": [{"id": "web"}],  # Enable real-time web search
    },
)

Dual-Provider Pattern

import os
from openai import OpenAI

def create_client(provider: str = "openrouter") -> OpenAI:
    if provider == "openai":
        return OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    return OpenAI(
        base_url="https://openrouter.ai/api/v1",
        api_key=os.environ["OPENROUTER_API_KEY"],
        default_headers={"HTTP-Referer": "https://your-app.com"},
    )

# Switch providers without changing application code
client = create_client(os.environ.get("LLM_PROVIDER", "openrouter"))

Error Handling

Issue	Cause	Fix
400 unsupported parameter	Model doesn't support a parameter	Conditionally set params based on model capabilities
Different response quality	Non-OpenAI model handles prompt differently	Adjust prompts per model family; test before switching
Missing organization	OpenRouter ignores org-level auth	Remove organization from client init

Enterprise Considerations

• Use environment variables to switch between direct OpenAI and OpenRouter without code changes
• Test your full prompt suite across providers before migrating production traffic
• Monitor response quality and latency after migration; some prompts may need tuning
• OpenRouter normalizes the API across providers, but subtle behavioral differences exist between model families
• Use extra_body for OpenRouter-specific features (provider preferences, plugins, fallbacks)

References

• Examples | Errors
• OpenRouter Quickstart | API Parameters