openrouter-openai-compat | openrouter-pack

Stats

Actions

Tags

openrouter-openai-compat | openrouter-pack

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