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.
Prerequisites
- An existing OpenAI SDK integration to migrate — Python or TypeScript code calling
chat.completions.create
- An OpenRouter API key exported as
OPENROUTER_API_KEY — see the openrouter-install-auth skill for setup
- Python 3.8+ with the
openai package, or Node.js 18+ with the openai npm package — the same SDK you already use, no new dependency
- Optionally keep
OPENAI_API_KEY exported too, so the Dual-Provider Pattern can switch back to direct OpenAI
Instructions
- Apply The Two-Line Migration: point
base_url at https://openrouter.ai/api/v1 and swap api_key to OPENROUTER_API_KEY; optionally add the HTTP-Referer / X-Title headers for app attribution.
- Prefix every model string per Model ID Mapping —
gpt-4o becomes openai/gpt-4o, o1 becomes openai/o1 — and try a non-OpenAI model (anthropic/claude-3.5-sonnet) through the same client.
- Confirm your feature usage against What Works Identically (streaming,
tools, JSON mode, stop, n) and adjust per What Differs — remove the organization param, plan around limited embeddings, and check logprobs support per model via /api/v1/models.
- Layer in OpenRouter-Only Features through
extra_body: ordered fallback model lists with "route": "fallback", provider preferences with sort: "price", or the plugins: [{"id": "web"}] web-search plugin.
- Keep the migration reversible with the Dual-Provider Pattern —
create_client() switches between direct OpenAI and OpenRouter off the LLM_PROVIDER environment variable.
The Two-Line Migration
Python (Before)
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
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",
api_key=os.environ["OPENROUTER_API_KEY"],
default_headers={
"HTTP-Referer": "https://your-app.com",
"X-Title": "Your App",
},
)
response = client.chat.completions.create(
model="openai/gpt-4o",
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:
response = client.chat.completions.create(
model="anthropic/claude-3.5-sonnet",
messages=[{"role": "user", "content": "Hello"}],
)
response = client.chat.completions.create(
model="google/gemini-2.0-flash",
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:
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",
},
)
response = client.chat.completions.create(
model="anthropic/claude-3.5-sonnet",
messages=[{"role": "user", "content": "Hello"}],
extra_body={
"provider": {
"order": ["anthropic"],
"allow_fallbacks": True,
"sort": "price",
},
},
)
response = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "What happened today?"}],
extra_body={
"plugins": [{"id": "web"}],
},
)
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"},
)
client = create_client(os.environ.get("LLM_PROVIDER", "openrouter"))
Output
- Standard OpenAI-SDK
ChatCompletion objects — choices[0].message.content, usage token counts, and model reporting the provider-prefixed ID that actually served the request
- The identical code path returning completions from non-OpenAI models (Claude, Gemini) with only the model string changed
- A provider-switchable client from
create_client() — flipping LLM_PROVIDER moves traffic between direct OpenAI and OpenRouter with zero application-code changes
Examples
After the two-line change, the untouched OpenAI SDK call round-trips through OpenRouter:
client = OpenAI(base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"])
response = client.chat.completions.create(
model="openai/gpt-3.5-turbo",
messages=[{"role": "user", "content": "What is the capital of France?"}],
max_tokens=100,
)
print(response.choices[0].message.content)
print(response.model)
Swap the model string to anthropic/claude-3.5-sonnet and the same code returns Claude's answer — that swap is the entire multi-provider story. More worked examples: references/examples.md.
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
