Building with AI today can feel messy. You might use one API for text, another for images, and a different one for something else. Every model comes with its own setup, API key, and billing. This slows you down and makes things harder than they need to be. What if you could use all these models through one simple API. That’s where OpenRouter helps. It gives you one place to access models from providers like OpenAI, Google, Anthropic and more. In this guide, you will learn how to use OpenRouter step by step, from your first API call to building real applications.
What is OpenRouter?
OpenRouter lets you access many AI models using a single API. You don’t need to set up each provider separately. You connect once, use one API key, and write one set of code. OpenRouter handles the rest, like authentication, request formatting, and billing. This makes it easy to try different models. You can switch between models like GPT-5, Claude 4.6, Gemini 3.1 Pro, or Llama 4 by changing just one parameter in your code. This helps you choose the right model based on cost, speed or features like reasoning and image understanding.
How OpenRouter Works?
OpenRouter acts as a bridge between your application and different AI providers. Your app sends a request to the OpenRouter API, and it converts that request into a standard format that any model can understand.
A state of the art routing engine is then involved. It will find the best provider of your request according to a set of rule that you can set. To give an example, it can be set to give preference to the most inexpensive provider, the one with the shortest latency, or merely those with a particular data privacy requirement such as Zero Data Retention (ZDR).
The platform keeps track of the performance and uptime of all the providers and as such, is able to make intelligent, real-time routing decisions. In case your preferred provider is not functioning properly, the OpenRouter fails over to a known-good one automatically and improves the stability of your application.
Getting Started: Your First API Call
OpenRouter is also easy to set up since it is a hosted service, i.e. there is no software to be installed. It can be ready in a matter of minutes:
Step 1: Create an Account and Get Credits:
First, sign up at OpenRouter.ai. To use the paid models, you will need to purchase some credits.
Step 2: Generate an API Key
Navigate to the “Keys” section in your account dashboard. Click “Create Key,” give it a name, and copy the key securely. For best practice, use separate keys for different environments (e.g., dev, prod) and set spending limits to control costs.
Step 3: Configure Your Environment
Store your API key in an environment variable to avoid exposing it in your code.
Step 4: Local Setup using an Environment Variable:
For macOS or Linux:
export OPENROUTER_API_KEY="your-secret-key-here"For Windows (PowerShell):
setx OPENROUTER_API_KEY "your-secret-key-here"Making a Request on OpenRouter
Since OpenRouter has an API that is compatible with OpenAI, you can use official OpenAI client libraries to make requests. This renders the process of migration of an already completed OpenAI project incredibly easy.
Python Example using the OpenAI SDK
# First, ensure you have the library installed:
# pip install openai
import os
from openai import OpenAI
# Initialize the client, pointing it to OpenRouter's API
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ.get("OPENROUTER_API_KEY"),
)
# Send a chat completion request to a specific model
response = client.chat.completions.create(
model="openai/gpt-4.1-nano",
messages=[
{
"role": "user",
"content": "Explain AI model routing in one sentence."
},
],
)
print(response.choices[0].message.content)Output:
Exploring Models and Advanced Routing
OpenRouter shows its true power beyond simple requests. Its platform supports dynamic and intelligent AI model routing.
Programmatically Discovering Models
As models are continuously added or updated, you are not supposed to hardcode model names in one of your production apps, instead openrouter has a /models endpoint that returns the list of all available models with suggested pricing, context limits and capabilities.
import os
import requests
# Fetch the list of available models
response = requests.get(
"https://openrouter.ai/api/v1/models",
headers={
"Authorization": f"Bearer {os.environ.get('OPENROUTER_API_KEY')}"
},
)
if response.status_code == 200:
models = response.json()["data"]
# Filter for models that support tool use
tool_use_models = [
m for m in models
if "tools" in (m.get("supported_parameters") or [])
]
print(f"Found {len(models)} total models.")
print(f"Found {len(tool_use_models)} models that support tool use.")
else:
print(f"Error fetching models: {response.text}"Output:
Intelligent Routing and Fallbacks
You are able to manage the way OpenRouter chooses a provider and can set backups in case of a request failure. This is the critical resilience of production systems.
- Routing: Send a provider object into your request to rank models by latency or price, or serve policies such as zdr (Zero Data Retention).
- Fallbacks: When the former fails, OpenRouter automatically attempts the following in the list. Only the successful attempt would be charged.
Here is a Python example demonstrating a fallback chain:
# The primary model is 'openai/gpt-4.1-nano'
# If it fails, OpenRouter will try 'anthropic/claude-3.5-sonnet',
# then 'google/gemini-2.5-pro'
response = client.chat.completions.create(
model="openai/gpt-4.1-nano",
extra_body={
"models": [
"anthropic/claude-3.5-sonnet",
"google/gemini-2.5-pro"
]
},
messages=[
{
"role": "user",
"content": "Write a short poem about space."
}
],
)
print(f"Model used: {response.model}")
print(response.choices[0].message.content)Output:
Mastering Advanced Capabilities
The same chat completions API can be used to send images to any vision capable model to analyze them. All that is needed is to add the image as a URL, or a base64-encoded string to your messages array.
Structured Outputs (JSON Mode)
Need a reliable JSON output? You can instruct any compatible model to return a response that conforms to a specific JSON schema.The OpenRouter even has an optional Response Healing plugin that can be used to repair malformed JSON due to models that have issues with strict formatting.
# Requesting a structured JSON output
response = client.chat.completions.create(
model="openai/gpt-4.1-nano",
messages=[
{
"role": "user",
"content": "Extract the name and age from this text: 'John is 30 years old.' in JSON format."
}
],
response_format={
"type": "json_object",
"json_schema": {
"name": "user_schema",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"}
},
"required": ["name", "age"],
},
},
},
)
print(response.choices[0].message.content)Output:
Multimodal Inputs: Working with Images
You can use the same chat completions API to send images to any vision-capable model for analysis. Simply add the image as a URL or a base64-encoded string to your messages array.
# Sending an image URL for analysis
response = client.chat.completions.create(
model="openai/gpt-4.1-nano",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is in this image?"
},
{
"type": "image_url",
"image_url": {
"url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRmqgVW-371UD3RgE3HwhF11LYbGcVfn9eiTYqiw6a8fK51Es4SYBK0fNVyCnJzQit6YKo9ze3vg1tYoWlwqp3qgiOmRxkTg1bxPwZK3A&s=10"
}
},
],
}
],
)
print(response.choices[0].message.content)Output:
A Cost-Aware, Multi-Provider Agent
The actual strength of OpenRouter lies in the development of advanced, affordable, and high availability applications. As an illustration, we can develop a realistic agent that will dynamically choose the best model to accomplish a specific task with the aid of a tiered approach to cheap-to-smart strategy.
The first thing that this agent will do is to attempt to respond to a query provided by a user using a fast and cheap model. In case that model is not good enough (e.g. in case the task involves deep reasoning) it will upwardly redirect the query to a more powerful, premium model. This is a typical trend when it comes to production applications which have to strike a balance between performance, price, and quality.
The “Cheap-to-Smart” Logic
Our agent will follow these steps:
- Receive a user’s prompt.
- Send the prompt to a low cost model at first.
- Examine the response to determine whether the model was able to respond to the request. One easy method of doing this is to request the model to provide a confidence score with its output.
- When the confidence is low, the agent will automatically repeat the same prompt with a high-end model which results in a good answer to a complex task.
This approach ensures you are not overpaying for simple requests while still having the power of top-tier models on demand.
Python Implementation
Here’s how you can implement this logic in Python. We will use structured outputs to ask the model for its confidence level, which makes parsing the response reliable.
from openai import OpenAI
import os
import json
# Initialize the client for OpenRouter
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ.get("OPENROUTER_API_KEY"),
)
def run_cheap_to_smart_agent(prompt: str):
"""
Runs a prompt first through a cheap model, then escalates to a
smarter model if confidence is low.
"""
cheap_model = "mistralai/mistral-7b-instruct"
smart_model = "openai/gpt-4.1-nano"
# Define the desired JSON structure for the response
json_schema = {
"type": "object",
"properties": {
"answer": {"type": "string"},
"confidence": {
"type": "integer",
"description": "A score from 1-100 indicating confidence in the answer.",
},
},
"required": ["answer", "confidence"],
}
# First, try the cheap model
print(f"--- Attempting with cheap model: {cheap_model} ---")
try:
response = client.chat.completions.create(
model=cheap_model,
messages=[
{
"role": "user",
"content": f"Answer the following prompt and provide a confidence score from 1-100. Prompt: {prompt}",
}
],
response_format={
"type": "json_object",
"json_schema": {
"name": "agent_response",
"schema": json_schema,
},
},
)
# Parse the JSON response
result = json.loads(response.choices[0].message.content)
answer = result.get("answer")
confidence = result.get("confidence", 0)
print(f"Cheap model confidence: {confidence}")
# If confidence is below a threshold (e.g., 70), escalate
if confidence < 70:
print(f"--- Confidence low. Escalating to smart model: {smart_model} ---")
# Use a simpler prompt for the smart model
smart_response = client.chat.completions.create(
model=smart_model,
messages=[
{
"role": "user",
"content": prompt,
}
],
)
final_answer = smart_response.choices[0].message.content
else:
final_answer = answer
except Exception as e:
print(f"An error occurred with the cheap model: {e}")
print(f"--- Falling back directly to smart model: {smart_model} ---")
smart_response = client.chat.completions.create(
model=smart_model,
messages=[
{
"role": "user",
"content": prompt,
}
],
)
final_answer = smart_response.choices[0].message.content
return final_answer
# --- Test the Agent ---
# 1. A simple prompt that the cheap model can handle
simple_prompt = "What is the capital of France?"
print(f"Final Answer for Simple Prompt:\n{run_cheap_to_smart_agent(simple_prompt)}\n")
# 2. A complex prompt that will likely require escalation
complex_prompt = "Provide a detailed comparison of the transformer architecture and recurrent neural networks, focusing on their respective advantages for sequence processing tasks."
print(f"Final Answer for Complex Prompt:\n{run_cheap_to_smart_agent(complex_prompt)}")Output:
This hands-on example goes beyond a simple API call and showcases how to architect a more intelligent, cost-effective system using OpenRouter’s core strengths: model variety and structured outputs.
Monitoring and Observability
Understanding your application’s performance and costs is crucial. OpenRouter provides built-in tools to help.
- Usage Accounting: Every API response contains detailed metadata about token usage and cost for that specific request, allowing for real-time expense tracking.
- Broadcast Feature: Without any extra code, you can configure OpenRouter to automatically send detailed traces of your API calls to observability platforms like Langfuse or Datadog. This provides deep insights into latency, errors, and performance across all models and providers.
Conclusion
The era of being tethered to a single AI provider is over. Tools like OpenRouter are fundamentally changing the developer experience by providing a layer of abstraction that unlocks unprecedented flexibility and resilience. By unifying the fragmented AI landscape, OpenRouter not only saves you from the tedious work of managing multiple integrations but also empowers you to build smarter, more cost-effective, and robust applications. The future of AI development is not about picking one winner; it is about having seamless access to them all. With this guide, you now have the map to navigate that future.
Frequently Asked Questions
A. OpenRouter provides a single, unified API to access hundreds of AI models from various providers. This simplifies development, enhances reliability with automatic fallbacks, and allows you to easily switch models to optimize for cost or performance.
A. No, it is designed to be an OpenAI-compatible API. You can use existing OpenAI SDKs and often only need to change the base URL to point to OpenRouter.
A. OpenRouter’s fallback feature automatically retries your request with a backup model you specify. This makes your application more resilient to provider outages.
A. Yes, you can set strict spending limits on each API key, with daily, weekly, or monthly reset schedules. Every API response also includes detailed cost data for real-time tracking.
A. Yes, OpenRouter supports structured outputs. You can provide a JSON schema in your request to force the model to return a response in a valid, predictable format.
Harsh Mishra is an AI/ML Engineer who spends more time talking to Large Language Models than actual humans. Passionate about GenAI, NLP, and making machines smarter (so they don’t replace him just yet). When not optimizing models, he’s probably optimizing his coffee intake. 🚀☕
Login to continue reading and enjoy expert-curated content.
💸 Earn Instantly With This Task
No fees, no waiting — your earnings could be 1 click away.
Start Earning