OpenRouter Provider

OpenRouter provides access to 400+ AI models from dozens of providers through a single API. This is ideal for:

• Multi-model workflows - Switch between Claude, GPT, Llama, and more
• Cost optimization - Route to the cheapest available provider
• Fallback resilience - Automatic failover when models are unavailable
• Unified billing - Single API key for all providers

Setup

Set your OpenRouter API key:

export OPENROUTER_API_KEY=sk-or-...

Optional analytics configuration:

export OPENROUTER_SITE_URL="https://myapp.com"    # Your app URL
export OPENROUTER_APP_NAME="MyApp"                 # Your app name

Tip

Get your API key at openrouter.ai/keys. OpenRouter offers free credits for new accounts.

Model Format

OpenRouter models use the format provider/model-name:

openrouter:anthropic/claude-sonnet-4-5
openrouter:openai/gpt-4o
openrouter:deepseek/deepseek-chat
openrouter:meta-llama/llama-3.3-70b-instruct

Note

Any valid OpenRouter model ID works—not just the ones in the catalog. Check openrouter.ai/models for the full list.

Popular Models

| Model | OpenRouter ID | Best For | |-------|---------------|----------| | Claude Sonnet 4.5 | anthropic/claude-sonnet-4-5 | Balanced performance | | GPT-4o | openai/gpt-4o | General tasks, vision | | DeepSeek Chat (V3) | deepseek/deepseek-chat | Cost-effective coding | | DeepSeek R1 | deepseek/deepseek-r1 | Complex reasoning | | Llama 3.3 70B | meta-llama/llama-3.3-70b-instruct | Open-source option | | Gemini 2.5 Flash | google/gemini-2.5-flash | Fast, long context |

Quick Aliases

llmist provides shortcuts for common OpenRouter models:

| Alias | Full Model | |-------|------------| | or:sonnet | openrouter:anthropic/claude-sonnet-4-5 | | or:opus | openrouter:anthropic/claude-opus-4-5 | | or:haiku | openrouter:anthropic/claude-haiku-4-5 | | or:gpt4o | openrouter:openai/gpt-4o | | or:gpt5 | openrouter:openai/gpt-5.2 | | or:flash | openrouter:google/gemini-2.5-flash | | or:llama | openrouter:meta-llama/llama-3.3-70b-instruct | | or:deepseek | openrouter:deepseek/deepseek-r1 |

Usage Examples

Basic

import { LLMist } from 'llmist';

const answer = await LLMist.createAgent()
  .withModel('openrouter:deepseek/deepseek-chat')
  .askAndCollect('Explain async/await in JavaScript');

Using Aliases

import { LLMist } from 'llmist';

// Use the or: prefix for quick access
const answer = await LLMist.createAgent()
  .withModel('or:sonnet')
  .askAndCollect('Write a haiku about coding');

CLI

# Full model ID
npx @llmist/cli complete "Hello" --model openrouter:deepseek/deepseek-chat

# Using alias
npx @llmist/cli agent "Review my code" --model or:sonnet

Routing Options

OpenRouter supports intelligent routing to optimize for cost, speed, or quality:

import { LLMist } from 'llmist';

const answer = await LLMist.createAgent()
  .withModel('openrouter:deepseek/deepseek-chat')
  .withExtra({
    routing: {
      route: 'cheapest',  // 'cheapest' | 'fastest' | 'quality'
    },
  })
  .askAndCollect('Hello!');

Route Options

| Option | Description | |--------|-------------| | quality | Best quality provider (default) | | cheapest | Lowest cost provider | | fastest | Lowest latency provider |

Model Fallbacks

Configure automatic fallback to alternative models:

import { LLMist } from 'llmist';

const answer = await LLMist.createAgent()
  .withModel('openrouter:anthropic/claude-sonnet-4-5')
  .withExtra({
    routing: {
      // Try these models in order if primary is unavailable
      models: [
        'anthropic/claude-sonnet-4-5',
        'openai/gpt-4o',
        'deepseek/deepseek-chat',
      ],
    },
  })
  .askAndCollect('Complex analysis task...');

Tip

Model fallbacks are great for production systems—they ensure your application keeps working even when a specific model has an outage.

Provider Routing

Route to a specific provider when a model is available from multiple sources:

const answer = await LLMist.createAgent()
  .withModel('openrouter:meta-llama/llama-3.3-70b-instruct')
  .withExtra({
    routing: {
      provider: 'Together',  // Route to Together AI
      // Or specify provider preference order:
      // order: ['Together', 'Fireworks', 'Anyscale'],
    },
  })
  .askAndCollect('Hello!');

Manual Configuration

For advanced setups, configure the provider manually:

import { LLMist, OpenRouterProvider } from 'llmist';
import OpenAI from 'openai';

const openRouterClient = new OpenAI({
  apiKey: process.env.OPENROUTER_API_KEY,
  baseURL: 'https://openrouter.ai/api/v1',
});

const client = new LLMist({
  autoDiscoverProviders: false,
  adapters: [
    new OpenRouterProvider(openRouterClient, {
      siteUrl: 'https://myapp.com',
      appName: 'MyApp',
    }),
  ],
});

When to Use OpenRouter

Use OpenRouter

• Access models not directly supported (Llama, Mistral, Qwen, etc.)
• Need automatic failover between providers
• Want unified billing across multiple models
• Optimizing for cost with dynamic routing
• Testing different models quickly

Use Direct Provider

• Maximum performance (lowest latency)
• Need provider-specific features
• Have negotiated enterprise pricing
• Compliance requires direct API access

Prompt Caching

llmist automatically enables prompt caching for OpenRouter requests. This works with both Anthropic Claude and Google Gemini models routed through OpenRouter, saving up to 75% on cached input tokens.

How It Works

llmist adds cache_control breakpoints to the last system message and last user message in each request. OpenRouter uses sticky routing to maximize cache hits by sending subsequent requests to the same provider endpoint.

For models with implicit caching (Gemini 2.5+, OpenAI, DeepSeek), caching happens server-side automatically — no breakpoints needed. llmist extracts and reports cached token counts from the API response in both cases.

Disable Caching

If needed, disable caching explicitly:

const answer = await LLMist.createAgent()
  .withModel('openrouter:anthropic/claude-sonnet-4-5')
  .withoutCaching()
  .askAndCollect('One-off question');

Tip

For long-running agent loops, caching can dramatically reduce costs. In a 94-iteration session processing 73 documents, enabling caching on Gemini Flash can reduce cumulative input tokens by 5-10x.

Cost Tracking

OpenRouter passes through usage information, including cached token counts:

for await (const event of agent.run()) {
  if (event.type === 'llm_call_complete') {
    console.log('Input tokens:', event.usage?.promptTokens);
    console.log('Output tokens:', event.usage?.completionTokens);
    console.log('Estimated cost:', event.cost);
  }
}

Note

OpenRouter pricing is dynamic and varies by provider. Check the OpenRouter pricing page for current rates.

Error Handling

The OpenRouter provider includes enhanced error messages:

| Error | Meaning | |-------|---------| | 401 | Invalid API key - check OPENROUTER_API_KEY | | 402 | Insufficient credits - add funds at openrouter.ai/credits | | 429 | Rate limit exceeded - reduce request frequency | | 503 | Model unavailable - try a different model or use fallbacks |

Reasoning Models via OpenRouter

OpenRouter provides access to reasoning-capable models like DeepSeek R1, which excels at math, logic, and coding with chain-of-thought reasoning:

const answer = await LLMist.createAgent()
  .withModel('openrouter:deepseek/deepseek-r1')
  .askAndCollect('Prove there are infinitely many primes.');

Note

Reasoning behavior for models accessed through OpenRouter depends on the upstream provider's support. For first-class reasoning support with withReasoning(), use direct provider connections (OpenAI, Anthropic, Gemini). See the Reasoning Models guide.

See Also

• OpenRouter Documentation
• Available Models
• Providers Overview