OpenRouter Provider

The OpenRouter provider enables access to 200+ AI models from multiple providers (OpenAI, Anthropic, Google, Meta, and more) through a unified API. It offers intelligent model routing, automatic fallbacks, multimodal support, PDF processing, and cost optimization features.

Configuration

Basic Setup

Configure OpenRouter in your agent:

ruby

class OpenRouterAgent < ApplicationAgent
  generate_with :open_router, model: "openrouter/auto"

  # @return [ActiveAgent::Generation]
  def ask
    prompt(message: params[:message])
  end
end

Basic Usage Example

ruby

response = Providers::OpenRouterAgent.with(
  message: "What is functional programming?"
).ask.generate_now

Response Example

Configuration File

Set up OpenRouter credentials in config/active_agent.yml:

yaml

open_router: &open_router
  service: "OpenRouter"
  access_token: <%= Rails.application.credentials.dig(:open_router, :access_token) || Rails.application.credentials.dig(:open_router, :api_key) %>

Environment Variables

Alternatively, use environment variables:

bash

OPEN_ROUTER_API_KEY=your-api-key
# or
OPENROUTER_API_KEY=your-api-key

Supported Models

OpenRouter provides access to 200+ models from multiple providers. For the complete list of available models and their capabilities, see OpenRouter Models.

Popular Models

Provider	Model	Context Window	Best For
OpenAI	openai/gpt-4o	128K tokens	Vision, structured output, complex reasoning
OpenAI	openai/gpt-4o-mini	128K tokens	Fast, cost-effective with vision support
Anthropic	anthropic/claude-3-5-sonnet	200K tokens	Balanced performance, coding, analysis
Anthropic	anthropic/claude-3-opus	200K tokens	Most capable Claude model
Google	google/gemini-pro-1.5	2M tokens	Very long context windows
Meta	meta-llama/llama-3.1-405b	128K tokens	Open source, powerful reasoning
Free	qwen/qwen3-30b-a3b:free	32K tokens	Free tier testing and development

Recommended model identifiers:

openai/gpt-4o - Best for vision tasks and structured output
anthropic/claude-3-5-sonnet - Best for coding and complex analysis
google/gemini-pro-1.5 - Best for extremely long documents

Model Prefixes

OpenRouter uses provider prefixes (e.g., openai/, anthropic/) to route requests to the correct provider. This allows you to use the same model across different providers or switch between them easily.

Provider-Specific Parameters

Required Parameters

model - Model identifier (e.g., "openai/gpt-4o", default: "openrouter/auto")

Sampling Parameters

temperature - Controls randomness (0.0 to 2.0, default: varies by model)
max_tokens - Maximum tokens to generate (minimum: 1)
top_p - Nucleus sampling parameter (0.0 to 1.0)
top_k - Top-k sampling parameter (integer ≥ 1)
frequency_penalty - Penalize frequent tokens (-2.0 to 2.0)
presence_penalty - Penalize new topics (-2.0 to 2.0)
repetition_penalty - Control repetition (0.0 to 2.0)
min_p - Minimum probability threshold (0.0 to 1.0)
top_a - Top-a sampling parameter (0.0 to 1.0)
seed - For deterministic outputs (integer)
stop - Stop sequences (string or array)

Tools & Functions

tools - Array of tool definitions for function calling
tool_choice - Control which tools can be used ("auto", "any", or specific tool)
parallel_tool_calls - Allow parallel tool execution (boolean)

Tool Calling Support

Tool calling support varies by model. Most modern models (GPT-4o, Claude 3.5, Gemini Pro) support function calling. Check the OpenRouter model documentation for specific model capabilities.

Response Format

response_format - Output format control (see Structured Output)

Predicted Outputs

prediction - Predicted output configuration for latency optimization (supported by compatible models)

OpenRouter-Specific Features

models (or fallback_models) - Array of fallback models for automatic failover
route - Routing strategy ("fallback")
transforms - Content transforms (e.g., ["middle-out"] for long context)
provider - Provider preferences (see Provider Preferences)
user - Stable user identifier for cost tracking and analytics

Client Configuration

access_token - OpenRouter API key (also accepts api_key)
uri_base - API endpoint (default: "https://openrouter.ai/api/v1")
app_name - Application name for usage attribution
site_url - Site URL for referral tracking and credits

Streaming

stream - Enable streaming responses (boolean, default: false)

Model Routing & Fallbacks

OpenRouter provides intelligent model routing with automatic fallbacks when models are unavailable or requests fail.

Automatic Fallbacks

Configure fallback models that will be tried in order if the primary model fails:

ruby

generate_with :open_router,
  model: "openai/gpt-4o",
  fallback_models: [ "anthropic/claude-sonnet-4", "google/gemini-pro-1.5" ],
  route: "fallback"

Fallback Behavior:

Models are tried in the order specified
Automatic retry on rate limits or availability issues
Seamless failover with no code changes needed
Cost optimization by trying cheaper alternatives first

Model Selection Strategies

Use the route parameter to control routing behavior:

ruby

generate_with :open_router,
  model: "openrouter/auto",  # Let OpenRouter choose
  route: "fallback"          # Enable automatic fallbacks

Available Routes:

fallback - Try models in order until one succeeds

Provider Preferences

Fine-tune which providers and configurations OpenRouter uses for your requests.

Basic Provider Configuration

ruby

generate_with :open_router,
  model: "openrouter/auto",
  provider: {
    data_collection: "deny",      # Privacy-first providers only
    allow_fallbacks: true,         # Enable backup providers
    require_parameters: false      # Flexible parameter support
  }

Provider Selection

Control which providers handle your requests:

ruby

generate_with :open_router,
  model: "openai/gpt-4o-mini",
  provider: {
    order:  [ "openai",   "azure" ],      # Try OpenAI first, then Azure
    only:   [ "openai",   "anthropic" ],  # Limit to specific providers
    ignore: [ "together", "huggingface" ] # Exclude specific providers
  }

Cost Optimization

Set maximum price constraints to control costs:

ruby

generate_with :open_router,
  model: "openrouter/auto",
  provider: {
    sort: "price",    # Sort by lowest cost
    max_price: {
      prompt: 0.3,    # Max $0.3 per 1M input tokens
      completion: 0.5 # Max $0.5 per 1M output tokens
    }
  }

Sorting Options:

price - Lowest cost providers first
throughput - Highest throughput providers first
latency - Lowest latency providers first

Privacy & Data Collection

Control data collection and privacy settings:

ruby

generate_with :open_router,
  model: "openrouter/auto",
  provider: {
    data_collection: "deny",    # Only use privacy-respecting providers
    zdr: true                   # Enable Zero Data Retention
  }

Data Collection Options:

allow (default) - Allow providers that may store/train on data
deny - Only use providers with strict no-data-retention policies

Quantization Control

Filter providers by model quantization level:

ruby

generate_with :open_router,
  model: "meta-llama/llama-3.1-405b",
  provider: {
    quantizations: [ "fp16", "bf16" ]  # Only use high-precision models
  }

Available Quantizations:

int4, int8 - Lower precision, faster inference
fp4, fp6, fp8 - Mixed precision
fp16, bf16 - High precision
fp32 - Full precision
unknown - Unspecified quantization

Content Transforms

OpenRouter provides content transforms to optimize long-context handling.

Middle-Out Compression

The middle-out transform automatically compresses the middle portion of long contexts while preserving the beginning and end:

ruby

prompt(
  "Summarize this document:\n\n#{long_text}",
  transforms: [ "middle-out" ]
)

Benefits:

Reduces token usage for long documents
Preserves important context at start/end
Lowers costs on long-context requests
Maintains coherent summaries

Cost Tracking & Analytics

OpenRouter provides detailed usage analytics when you configure tracking parameters.

User Tracking

Track costs per user with the user parameter:

ruby

generate_with :open_router,
  model: "openrouter/auto",
  user: -> { Current.user&.id } # Track per-user costs

Application Attribution

Configure app tracking for referral credits:

ruby

generate_with :open_router,
  model: "openrouter/auto",
  app_name: "MyApp",
  site_url: "https://myapp.com"

Benefits:

Earn referral credits for traffic
Track usage across applications
Detailed cost breakdowns in OpenRouter dashboard
Per-user and per-model analytics

Multimodal Support

OpenRouter supports vision-capable models for image analysis and multimodal tasks.

Image Analysis

ruby

class VisionAgent < ApplicationAgent
  generate_with :open_router,
    model: "openai/gpt-4o"  # Vision-capable model

  def analyze_image
    prompt("What's in this image?", image: params[:image_url])
  end
end

Vision-Capable Models:

openai/gpt-4o - Best vision performance
openai/gpt-4o-mini - Fast, cost-effective vision
anthropic/claude-3-5-sonnet - Strong vision + reasoning
google/gemini-pro-vision - Google's vision model

PDF Processing

OpenRouter provides built-in PDF processing capabilities through plugins.

PDF Document Analysis

ruby

class PDFAgent < ApplicationAgent
  generate_with :open_router,
    model: "openai/gpt-4o"

  def analyze_pdf
    prompt(
      "Summarize this PDF",
      document: params[:pdf_base64_url],
      plugins: [ {
        id: "file-parser",
        pdf: { engine: "pdf-text" }  # Free text extraction
      } ]
    )
  end
end

PDF Processing Engines:

pdf-text (free) - Text extraction from PDFs
mistral-ocr ($2/1000 pages) - OCR for scanned documents
native (input tokens) - Model's native PDF support

Best Practices

1. Use Fallbacks for Reliability

Always configure fallback models for production systems:

ruby

fallback_models: [ "anthropic/claude-sonnet-4", "google/gemini-pro-1.5" ]

2. Optimize Costs with Provider Preferences

Use cost-based sorting and price limits:

ruby

model: "openrouter/auto",
provider: {
  sort: "price",
  max_price: { prompt: 0.3, completion: 0.5 }
}

3. Track Usage Per User

Enable detailed analytics:

ruby

user: -> { Current.user&.id },
app_name: "MyApp"

4. Use Transforms for Long Content

Apply middle-out compression for documents:

ruby

transforms: [ "middle-out" ]

5. Respect Privacy with Provider Settings

For sensitive data, use privacy-first providers:

ruby

provider: {
  data_collection: "deny",
  zdr: true
}

Structured Output - Comprehensive structured output guide
Data Extraction Agent - Data extraction examples
Providers Overview - Provider architecture
Configuration Guide - General configuration
OpenRouter API Documentation - Official OpenRouter docs
OpenRouter Provider Routing - Advanced routing documentation

OpenRouter Provider ​

Configuration ​

Basic Setup ​

Basic Usage Example ​

Configuration File ​

Environment Variables ​

Supported Models ​

Popular Models ​

Provider-Specific Parameters ​

Required Parameters ​

Sampling Parameters ​

Tools & Functions ​

Response Format ​

Predicted Outputs ​

OpenRouter-Specific Features ​

Client Configuration ​

Streaming ​

Model Routing & Fallbacks ​

Automatic Fallbacks ​

Model Selection Strategies ​

Provider Preferences ​

Basic Provider Configuration ​

Provider Selection ​

Cost Optimization ​

Privacy & Data Collection ​

Quantization Control ​

Content Transforms ​

Middle-Out Compression ​

Cost Tracking & Analytics ​

User Tracking ​

Application Attribution ​

Multimodal Support ​

Image Analysis ​

PDF Processing ​

PDF Document Analysis ​

Best Practices ​

1. Use Fallbacks for Reliability ​

2. Optimize Costs with Provider Preferences ​

3. Track Usage Per User ​

4. Use Transforms for Long Content ​

5. Respect Privacy with Provider Settings ​

Related Documentation ​

OpenRouter Provider

Configuration

Basic Setup

Basic Usage Example

Configuration File

Environment Variables

Supported Models

Popular Models

Provider-Specific Parameters

Required Parameters

Sampling Parameters

Tools & Functions

Response Format

Predicted Outputs

OpenRouter-Specific Features

Client Configuration

Streaming

Model Routing & Fallbacks

Automatic Fallbacks

Model Selection Strategies

Provider Preferences

Basic Provider Configuration

Provider Selection

Cost Optimization

Privacy & Data Collection

Quantization Control

Content Transforms

Middle-Out Compression

Cost Tracking & Analytics

User Tracking

Application Attribution

Multimodal Support

Image Analysis

PDF Processing

PDF Document Analysis

Best Practices

1. Use Fallbacks for Reliability

2. Optimize Costs with Provider Preferences

3. Track Usage Per User

4. Use Transforms for Long Content

5. Respect Privacy with Provider Settings

Related Documentation