A Guide to OpenRouter for AI Development

Constructing with AI at the moment can really feel messy. You would possibly use one API for textual content, one other for pictures, and a special one for one thing else. Each mannequin comes with its personal setup, API key, and billing. This slows you down and makes issues more durable than they have to be. What in the event you may use all these fashions by way of one easy API. That’s the place OpenRouter helps. It offers you one place to entry fashions from suppliers like OpenAI, Google, Anthropic and extra. On this information, you’ll learn to use OpenRouter step-by-step, out of your first API name to constructing actual purposes. 

What’s OpenRouter? 

OpenRouter allows you to entry many AI fashions utilizing a single API. You don’t have to arrange every supplier individually. You join as soon as, use one API key, and write one set of code. OpenRouter handles the remaining, like authentication, request formatting, and billing. This makes it straightforward to strive totally different fashions. You’ll be able to change between fashions like GPT-5, Claude 4.6, Gemini 3.1 Professional, or Llama 4 by altering only one parameter in your code. This helps you select the best mannequin based mostly on price, pace or options like reasoning and picture understanding.

How OpenRouter Works?

OpenRouter acts as a bridge between your software and totally different AI suppliers. Your app sends a request to the OpenRouter API, and it converts that request into a regular format that any mannequin can perceive. 

A state-of-the-art routing engine is then concerned. It is going to discover the perfect supplier of your request in accordance with a set of rule that you would be able to set. To provide an instance, it may be set to provide desire to essentially the most cheap supplier, the one with the shortest latency, or merely these with a specific information privateness requirement comparable to Zero Knowledge Retention (ZDR).

The platform retains observe of the efficiency and uptime of all of the suppliers and as such, is ready to make clever, real-time routing choices. In case your most popular supplier shouldn’t be functioning correctly, the OpenRouter fails over to a known-good one routinely and improves the steadiness of your software. 

Getting Began: Your First API Name 

OpenRouter can also be straightforward to arrange since it’s a hosted service, i.e. there isn’t a software program to be put in. It may be prepared in a matter of minutes:

Step 1: Create an Account and Get Credit:

First, enroll at OpenRouter.ai. To make use of the paid fashions, you’ll need to buy some credit.

Step 2: Generate an API Key

Navigate to the “Keys” part in your account dashboard. Click on “Create Key,” give it a reputation, and replica the important thing securely. For greatest apply, use separate keys for various environments (e.g., dev, prod) and set spending limits to manage prices.

Step 3: Configure Your Setting

Retailer your API key in an atmosphere variable to keep away from exposing it in your code.

Step 4: Native Setup utilizing an Setting Variable:

For macOS or Linux:

export OPENROUTER_API_KEY="your-secret-key-here"

For Home windows (PowerShell):

setx OPENROUTER_API_KEY "your-secret-key-here"

Making a Request on OpenRouter

Since OpenRouter has an API that’s suitable with OpenAI, you should use official OpenAI shopper libraries to make requests. This renders the method of migration of an already accomplished OpenAI mission extremely straightforward.

Python Instance utilizing the OpenAI SDK 

# First, guarantee you've gotten the library put in:
# pip set up openai

import os
from openai import OpenAI

# Initialize the shopper, pointing it to OpenRouter's API
shopper = OpenAI(
    base_url="
    api_key=os.environ.get("OPENROUTER_API_KEY"),
)

# Ship a chat completion request to a selected mannequin
response = shopper.chat.completions.create(
    mannequin="openai/gpt-4.1-nano",
    messages=[
        {
            "role": "user",
            "content": "Explain AI model routing in one sentence."
        },
    ],
)

print(response.selections[0].message.content material)

Output:

Exploring Fashions and Superior Routing 

OpenRouter exhibits its true energy past easy requests. Its platform helps dynamic and clever AI mannequin routing.

Programmatically Discovering Fashions 

As fashions are constantly added or up to date, you aren’t presupposed to hardcode mannequin names in one in all your manufacturing apps, as an alternative openrouter has a /fashions endpoint that returns the checklist of all obtainable fashions with prompt pricing, context limits and capabilities. 

import os
import requests

# Fetch the checklist of accessible fashions
response = requests.get(
    "
    headers={
        "Authorization": f"Bearer {os.environ.get('OPENROUTER_API_KEY')}"
    },
)

if response.status_code == 200:
    fashions = response.json()["data"]

    # Filter for fashions that assist instrument use
    tool_use_models = [
        m for m in models
        if "tools" in (m.get("supported_parameters") or [])
    ]

    print(f"Discovered {len(fashions)} complete fashions.")
    print(f"Discovered {len(tool_use_models)} fashions that assist instrument use.")
else:
    print(f"Error fetching fashions: {response.textual content}"

Output:

Clever Routing and Fallbacks 

You’ll be able to handle the way in which OpenRouter chooses a supplier and may set backups in case of a request failure. That is the crucial resilience of manufacturing techniques. 

• Routing: Ship a supplier object into your request to rank fashions by latency or worth, or serve insurance policies comparable to zdr (Zero Knowledge Retention). 
• Fallbacks: When the previous fails, OpenRouter routinely makes an attempt the next within the checklist. Solely the profitable try could be charged. 

Here’s a Python instance demonstrating a fallback chain:

# The first mannequin is 'openai/gpt-4.1-nano'
# If it fails, OpenRouter will strive 'anthropic/claude-3.5-sonnet',
# then 'google/gemini-2.5-pro'

response = shopper.chat.completions.create(
    mannequin="openai/gpt-4.1-nano",
    extra_body={
        "fashions": [
            "anthropic/claude-3.5-sonnet",
            "google/gemini-2.5-pro"
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Write a short poem about space."
        }
    ],
)

print(f"Mannequin used: {response.mannequin}")
print(response.selections[0].message.content material)

Output:

Mastering Superior Capabilities

The identical chat completions API can be utilized to ship pictures to any imaginative and prescient succesful mannequin to investigate them. All that’s wanted is so as to add the picture as a URL, or a base64-encoded string to your messages array. 

Structured Outputs (JSON Mode)

Want a dependable JSON output? You’ll be able to instruct any suitable mannequin to return a response that conforms to a selected JSON schema.The OpenRouter even has an non-obligatory Response Therapeutic plugin that can be utilized to restore malformed JSON as a consequence of fashions which have points with strict formatting.

# Requesting a structured JSON output

response = shopper.chat.completions.create(
    mannequin="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={
        "sort": "json_object",
        "json_schema": {
            "title": "user_schema",
            "schema": {
                "sort": "object",
                "properties": {
                    "title": {"sort": "string"},
                    "age": {"sort": "integer"}
                },
                "required": ["name", "age"],
            },
        },
    },
)

print(response.selections[0].message.content material)

Output:

Multimodal Inputs: Working with Photos 

You need to use the identical chat completions API to ship pictures to any vision-capable mannequin for evaluation. Merely add the picture as a URL or a base64-encoded string to your messages array.

# Sending a picture URL for evaluation

response = shopper.chat.completions.create(
    mannequin="openai/gpt-4.1-nano",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is in this image?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "
                    }
                },
            ],
        }
    ],
)

print(response.selections[0].message.content material)

Output:

A Price-Conscious, Multi-Supplier Agent

The precise energy of OpenRouter lies within the improvement of superior, reasonably priced, and excessive availability purposes. As an illustration, we are able to develop a sensible agent that can dynamically select the perfect mannequin to accomplish a selected activity with the help of a tiered strategy to cheap-to-smart technique. 

The very first thing that this agent will do is to try to reply to a question supplied by a person utilizing a quick and low cost mannequin. In case that mannequin shouldn’t be adequate (e.g. in case the duty entails deep reasoning) it will upwardly redirect the question to a extra highly effective, premium mannequin. It is a typical development in relation to manufacturing purposes which must strike a stability between efficiency, worth, and high quality. 

The “Low-cost-to-Sensible” Logic

Our agent will comply with these steps: 

• Obtain a person’s immediate. 
• Ship the immediate to a low price mannequin at first. 
• Study the response to decide whether or not the mannequin was in a position to reply to the request. One straightforward technique of doing that is to request the mannequin to supply a confidence rating with its output. 
• When the arrogance is low, the agent will routinely repeat the identical immediate with a high-end mannequin which ends up in a superb reply to a posh activity. 

This strategy ensures you aren’t overpaying for easy requests whereas nonetheless having the facility of top-tier fashions on demand. 

Python Implementation

Right here’s how one can implement this logic in Python. We’ll use structured outputs to ask the mannequin for its confidence degree, which makes parsing the response dependable. 

from openai import OpenAI
import os
import json

# Initialize the shopper for OpenRouter
shopper = OpenAI(
    base_url="
    api_key=os.environ.get("OPENROUTER_API_KEY"),
)


def run_cheap_to_smart_agent(immediate: str):
    """
    Runs a immediate first by way of an inexpensive mannequin, then escalates to a
    smarter mannequin if confidence is low.
    """

    cheap_model = "mistralai/mistral-7b-instruct"
    smart_model = "openai/gpt-4.1-nano"

    # Outline the specified JSON construction for the response
    json_schema = {
        "sort": "object",
        "properties": {
            "reply": {"sort": "string"},
            "confidence": {
                "sort": "integer",
                "description": "A rating from 1-100 indicating confidence within the reply.",
            },
        },
        "required": ["answer", "confidence"],
    }

    # First, strive a budget mannequin
    print(f"--- Making an attempt with low cost mannequin: {cheap_model} ---")

    strive:
        response = shopper.chat.completions.create(
            mannequin=cheap_model,
            messages=[
                {
                    "role": "user",
                    "content": f"Answer the following prompt and provide a confidence score from 1-100. Prompt: {prompt}",
                }
            ],
            response_format={
                "sort": "json_object",
                "json_schema": {
                    "title": "agent_response",
                    "schema": json_schema,
                },
            },
        )

        # Parse the JSON response
        outcome = json.hundreds(response.selections[0].message.content material)
        reply = outcome.get("reply")
        confidence = outcome.get("confidence", 0)

        print(f"Low-cost mannequin confidence: {confidence}")

        # If confidence is under a threshold (e.g., 70), escalate
        if confidence < 70:
            print(f"--- Confidence low. Escalating to good mannequin: {smart_model} ---")

            # Use a less complicated immediate for the good mannequin
            smart_response = shopper.chat.completions.create(
                mannequin=smart_model,
                messages=[
                    {
                        "role": "user",
                        "content": prompt,
                    }
                ],
            )

            final_answer = smart_response.selections[0].message.content material
        else:
            final_answer = reply

    besides Exception as e:
        print(f"An error occurred with a budget mannequin: {e}")
        print(f"--- Falling again on to good mannequin: {smart_model} ---")

        smart_response = shopper.chat.completions.create(
            mannequin=smart_model,
            messages=[
                {
                    "role": "user",
                    "content": prompt,
                }
            ],
        )

        final_answer = smart_response.selections[0].message.content material

    return final_answer


# --- Check the Agent ---

# 1. A easy immediate that a budget mannequin can deal with
simple_prompt = "What's the capital of France?"
print(f"Closing Reply for Easy Immediate:n{run_cheap_to_smart_agent(simple_prompt)}n")

# 2. A posh immediate that can doubtless require escalation
complex_prompt = "Present an in depth comparability of the transformer structure and recurrent neural networks, specializing in their respective benefits for sequence processing duties."
print(f"Closing Reply for Complicated Immediate:n{run_cheap_to_smart_agent(complex_prompt)}")

Output:

This hands-on instance goes past a easy API name and showcases the way to architect a extra clever, cost-effective system utilizing OpenRouter’s core strengths: mannequin selection and structured outputs. 

Monitoring and Observability

Understanding your software’s efficiency and prices is essential. OpenRouter supplies built-in instruments to assist. 

• Utilization Accounting: Each API response accommodates detailed metadata about token utilization and value for that particular request, permitting for real-time expense monitoring. 
• Broadcast Function: With none additional code, you possibly can configure OpenRouter to routinely ship detailed traces of your API calls to observability platforms like Langfuse or Datadog. This supplies deep insights into latency, errors, and efficiency throughout all fashions and suppliers. 

Conclusion

The period of being tethered to a single AI supplier is over. Instruments like OpenRouter are basically altering the developer expertise by offering a layer of abstraction that unlocks unprecedented flexibility and resilience. By unifying the fragmented AI panorama, OpenRouter not solely saves you from the tedious work of managing a number of integrations but in addition empowers you to construct smarter, cheaper, and strong purposes. The way forward for AI improvement shouldn’t be about selecting one winner; it’s about having seamless entry to all of them. With this information, you now have the map to navigate that future. 

Continuously Requested Questions